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Preface  What's  in  this  volume 


This  third  volume  of  the  Apple  IIGS  Toolbox  Reference  contains  new 
material  describing  numerous  changes  to  the  Apple  IIGS®  Toolbox.  There 
are  six  previously  undocumented  tool  sets,  many  new  tool  calls,  and 
numerous  corrections  and  additions.  This  document  comprises  both  new 
material  and  information  issued  in  a  previous  update  that  was  available 
only  from  APDA™  (the  Apple  Programmers  and  Developers  Association). 
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Organization 

Like  the  first  two  volumes  of  the  Apple  IIGS  Toolbox  Reference,  this  book  contains  chapters 
that  are  devoted  to  individual  tool  sets  or  managers.  The  chapters  are  arranged 
alphabetically  by  tool  set  name.  Chapters  documenting  the  six  new  tool  sets  appear  in 
alphabetical  order  among  the  other  chapters.  Chapters  that  discuss  previously  existing 
tool  sets  or  managers  carry  the  same  tides  as  before,  with  the  addition  of  the  word 
Update.  Note  that  chapters  in  this  book  have  been  numbered  sequentially  following  the 
last  chapter  in  Volume  2  of  the  Toolbox  Reference. 

Each  chapter  contains  a  brief  introductory  note,  which  indicates  whether  the  chapter 
updates  existing  material  or  describes  a  new  tool  set  or  manager.  Update  chapters  contain 
one  or  more  of  these  sections: 

Error  corrections       Corrects  errors  in  the  previous  toolbox  documentation 
Clarifications  Provides  additional  information  about  previously  documented 

toolbox  features,  including  bug  fixes 
New  features  Describes  new  tool  set  features 

New  tool  calls  Defines  new  tool  calls 

New  chapters  follow  the  organizational  style  of  the  first  two  volumes. 

In  addition  to  the  chapters  that  discuss  the  various  tool  sets  and  managers,  this  book 
contains  several  appendixes: 

Appendix  E  ("Resource  Types")  Contains  format  and  content  information  for  all 

defined  Apple  IIGS  resource  types 

Appendix  F  ("Delta  Guide")  Collects  all  corrections  to  and  clarifications  of 

the  previous  volumes  of  the  Toolbox  Reference 
in  a  single  location 


Typographical  conventions 

This  update  largely  obeys  the  typographical  conventions  of  the  Apple  IIGS  Toolbox 
Reference.  New  terms  appear  in  boldface  when  they  are  introduced.  Tool  call  parameter 
names  are  given  in  italics.  Record  field  names,  routine  names,  and  code  listings  appear  in 
the  Courier  font. 

For  the  Beta  draft,  new  or  substantially  changed  text  carries  change  bars. 
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Call  format 

This  book  documents  tool  calls  for  all  the  new  tool  sets  and  several  of  the  existing  tool 
sets. 

Certain  elements  of  this  format  may  not  appear  in  all  alls.  For  example,  not  all  calls  return 
error  codes,  and  so  not  all  call  descriptions  contain  a  list  of  error  codes.  Similarly,  stack 
diagrams  are  omitted  from  those  calls  that  do  not  affect  the  stack. 


ToolCallName    $callnumber 

A  description  of  the  call's  function. 

Parameters 

Stack  before  call 


Previous  contents 


-  longParmName  - 


wordParmName 


Long— Description  of  longParmName  parameter 
Word— Description  of  wordParmName  parameter 
<— SP 


Stack  after  call 


Previous  contents 


Result 


Long— Description  of  call  result  value  (if  any) 

<— SP 

Errors  $xxxx        Error  name  Description  of  the  error  code 

C  The  C  language   function  declaration   for  the  call. 

stackField  Detailed  description  of  stack  input  or  output  parameter,  where 

appropriate. 
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Indexes 

Volume  3  contains  three  indexes.  First,  there  is  an  index  of  calls  that  are  new  in  this 
update,  arranged  alphabetically.  Next  is  an  index  listing  all  tool  calls,  both  those  in  the 
Apple  JIGS  Toolbox  Reference  and  those  documented  in  this  volume.  This  index  is  included 
to  make  it  easier  to  find  a  particular  call's  description,  whether  it  is  a  new  call  or  one  that 
was  previously  documented.  Finally,  there  is  a  general  index  covering  both  this  book  and 
the  first  two  volumes  of  the  Apple  IIGS  Toolbox  Reference. 

Note  that  the  Beta  draft  only  has  a  single  index,  covering  the  contents  of  Volume  3. 
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Chapter  26   Apple  Desktop  Bus  Tool  Set  Update 


This  chapter  contains  new  information  about  the  Apple®  Desktop  Bus™ 
Tool  Set.  The  complete  reference  to  this  tool  set  is  in  Volume  1, 
Chapter  3  of  the  Apple  IIGS  Toolbox  Reference. 
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Error  correction 

The  parameter  table  for  the  ReadKeyMicroData  tool  call  ($0A09)  in  Volume  1  of  the 
Toolbox  Reference  incorrectly  describes  the  format  for  the  readconf  ig  command  ($0B). 
The  description  should  be  as  follows. 


Command 


dataLength 


Name 


Action 


$0B  3  readconf  ig    Read  configuration;  dataPtr  refers  to  a 

3-byte  data  structure: 
Byte     ADB  keyboard  and  mouse 
addresses 

low  nibble  -  keyboard 
high  nibble  -  mouse 
Byte     Keyboard  layout  and  display 
language 

low  nibble  -  keyboard  layout 
high  nibble  -  display  language 
Byte     Repeat  rate  and  delay 
low  nibble  -  repeat  rate 
high  nibble  -  repeat  delay 

The  description  of  this  configuration  record  is  also  wrong  in  the  tool  set  summary.  The 
following  table  shows  the  correct  information. 


Name 


Offset 


Type 


Definition 


ReadConf  igRec  (configuration  record  for  ReadKeyMicroData) 
rcADBAddr  $0000 


rcLayoutOrLang 


rcRepeatDelay  $0002 


Byte 


$0001 


Byte 


ADB  keyboard  and  mouse  addresses 

low  nibble  -  keyboard 

high  nibble  -  mouse 

Byte  Keyboard  layout  and 

display  language 

low  nibble  -  keyboard  layout 

high  nibble  -  display  language 

Repeat  rate  and  delay 

low  nibble  -  repeat  rate 

high  nibble  -  repeat  delay 
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Clarification 

This  section  presents  new  information  about  the  AsyncADBReceive  call. 

You  can  call  AsyncADBReceive  to  poll  a  device  using  register  2,  and  it  will  return  certain 
useful  information  about  the  status  of  the  keyboard.  The  call  returns  the  following 
information  in  the  specified  bits  of  register  2: 

Bit  5:    O-Caps  Lock  key  down 
1-Caps  Lock  key  up 

Bit  3:    O-Control  key  down 
1 -Control  key  up 

Bit  2:    O-Shift  key  down 
1-Shift  key  up 

Bit  1:    0-Option  key  down 
1-Option  key  up 

Bit  0:    0-Command  key  down 
1-Command  key  up 
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Chapter  27  Audio  Compression  and 
Expansion  Tool  Set 


This  chapter  documents  the  features  of  the  new  Audio  Compression  and 
Expansion  (ACE)  Tool  Set.  This  is  a  new  tool  set,  not  previously 
documented  in  the  Apple  IIGS  Toolbox  Reference. 
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Error  correction 


This  is  a  note  to  call  to  your  attention  an  error  in  the  Apple  IIGS  Toolbox  Reference  Update 
(distributed  by  APDA™).  The  description  for  the  ACEExpand  tool  call  carried  an 
incorrect  parameter  block.  This  book  contains  a  corrected  description. 


About  Audio  Compression  and  Expansion 

The  Audio  Compression  and  Expansion  (ACE)  tools  are  a  set  of  utility  routines  that 
compress  and  expand  digital  audio  data.  The  tool  set  is  designed  to  support  a  variety  of 
methods  of  audio  signal  compression,  but  at  present  only  one  method  is  implemented. 

With  the  present  method  of  compression  supported  by  the  ACE  tools,  you  can  choose 
either  of  two  compression  ratios.  You  can  compress  a  digital  audio  signal  to  half  its 
original  size  or  to  three-eighths  its  original  size.  The  ratio  used  is  determined  by  a 
parameter  of  the  ACE  call  that  does  the  compression  or  expansion. 

The  obvious  advantages  of  compressing  an  audio  signal  are  that  it  takes  up  less  space  on 
the  disk,  and  less  time  is  needed  to  transfer  the  data.  A  digital  sample  that  is  compressed 
to  half  its  original  size  occupies  only  half  the  space  and  takes  only  half  as  long  to  transfer. 
Such  a  sample  can  load  from  the  disk  twice  as  fast  as  the  uncompressed  version,  and  is 
much  more  economical  to  upload  to  or  download  from  a  commercial  computer  network. 
Note,  however,  that  data  compression  and  expansion  requires  significant  processor 
resources,  and  therefore  takes  some  time. 
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Uses  of  the  ACE  Tool  Set 


Software  often  includes  sound  effects,  music,  or  speech.  The  problem  with  digitized 
sound  is  that  it  requires  considerable  storage  space.  A  faithful  monophonic  digitization 
of  30  seconds  of  an  FM  radio  signal  occupies  nearly  a  megabyte  (MB)  of  disk  space.  A  user 
might  be  somewhat  reluctant  to  use  a  program  that  occupies  so  much  space  only  to 
achieve  sound  effects.  The  ACE  Tool  Set  provides  you  with  the  means  to  compress 
digitized  sound  signals  to  minimize  this  problem. 

ACE  presently  supports  Adaptive  Differential  Pulse  Code  Modulation  (ADPCM).  This 
compression  method  assumes  that  audio  signals  tend  to  be  relatively  smooth  and 
continuous.  If  the  amplitude  (loudness)  of  a  typical  audio  signal  is  plotted  against  time, 
the  graph  is  relatively  smooth  compared  to  a  spreadsheet,  a  text  document,  or  other 
typical  files  that  may  contain  arbitrarily  distributed  byte-values.  As  a  result,  it  is  possible 
to  compute  the  probable  value  of  the  next  sample  in  the  signal.  ADPCM  uses  a  static 
model  of  what  the  change  between  any  given  value  and  the  next  might  likely  be  and  a 
dynamic  model  of  what  the  next  actual  change  should  be,  based  on  the  values  last 
observed.  It  examines  the  next  signal  to  compare  its  predictions  against  the  observed 
value,  and  then  encodes  the  difference  between  its  prediction  and  the  actual  value. 

ADPCM  relies  on  the  relative  predictability  of  audio  signals.  If  the  changes  in  an  audio 
signal  are  too  great  or  sudden,  the  value  that  ADPCM  records  will  be  erroneous.  In  general, 
there  is  a  certain  statistically  predictable  amount  of  error  that  appears  in  any  signal  that  is 
compressed  by  this  method.  The  errors  appear,  not  as  distortions  of  the  quality  of  the 
sound,  but  as  pink  noise,  or  hiss,  much  like  the  hiss  on  ordinary  cassette  recordings.  Thus, 
although  ADPCM  compression  is  suitable  for  many  sound  compression  tasks,  particularly 
for  sound  effects  or  speech  in  games  or  business  software,  it  is  not  the  best  choice  for 
very  high-fidelity  reproduction.  A  signal  compressed  by  the  ADPCM  method  will  likely  be 
too  noisy  for  use  in  professional  audio,  such  as  film  soundtrack  recording. 
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How  ADPCM  works 

The  ADPCM  method  assumes  that  any  particular  digital  sample  in  a  block  of  audio  data 
has  a  value  that  is  relatively  close  to  those  on  either  side  of  it.  In  fact,  the  noise  in  the 
reproduced  signal  arises  from  samples  that  vary  more  than  the  method  supports.  ADPCM 
predicts  what  the  next  value  will  be,  and  compares  it  with  the  value  that  is  actually  there. 
The  difference  is  encoded  in  a  value  that  is  some  number  of  bits  in  size,  that  size  being 
specified  by  the  application  code.  With  ADPCM  the  programmer  can  specify  encoded 
values  either  3  or  4  bits  wide.  Since  the  original  data  is  stored  in  8-bit  samples,  the 
compression  rate  is  either  8  to  3  or  8  to  4,  depending  on  which  size  a  particular  program 
specifies. 

Errors  result  when  the  difference  between  the  original  signal  and  the  value  that  ADPCM 
predicts  is  greater  than  can  be  encoded  in  the  specified  number  of  bits.  The  encoded 
value  then  effectively  becomes  a  random  value,  and  so  is  perceived  as  audio  noise.  If  the 
target  code  is  3  bits  wide,  then  the  difference  observed  by  the  compression  algorithm  is 
more  likely  to  be  out  of  range  than  if  the  code  size  is  4  bits.  Greater  compression 
therefore  results  in  greater  loss  of  fidelity. 

As  stated  earlier,  the  fidelity  loss  sounds  like  hiss,  not  like  a  gross  distortion  of  the  audio 
signal.  Even  using  inaccurate  predictive  models,  ADPCM  tends  to  produce  hiss  rather  than 
more  offensive  forms  of  distortion.  The  technique  tracks  the  gross  characteristics  of 
audio  signals  well  even  when  the  rate  of  errors  is  high.  At  worst,  an  expanded  signal  sounds 
faithful  to  the  original,  though  muffled  by  noise. 

A  Important      The  noisier  a  sampled  signal  is,  the  noisier  the  sample  compressed  by 
using  ADPCM  will  be.  Any  noise  that  is  introduced  into  the  signal 
produces  discontinuities  in  the  audio  data  and  causes  errors  in  the 
compression  and  expansion  process.  For  this  reason,  any  editing, 
equalization,  or  other  sound-processing  effects  should  be  applied  to 
the  original  signal  before  it  is  compressed.  ADPCM  compression 
should  be  the  last  process  applied  to  an  audio  signal  before  it  is  stored 
on  the  final  disk,  a 
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ACE  housekeeping  routines 

These  routines  allow  you  to  start  and  stop  the  ACE  tools  and  to  obtain  tool  set  status 
information. 


ACEBootlnit     $011D 

Performs  any  initializations  of  the  ACE  tools  that  are  necessary  at  boot  time. 

▲  Warning       Applications  must  not  make  this  call.  ▲ 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  ACEBootlnit () ; 
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ACEStartUp     $021D 


Initializes  the  ACE  tools  for  use  by  an  application.  ACEStartUp  sets  aside  a  region  of 
bank  $00,  specified  by  dPageAddr,  for  use  as  the  ACE  tools'  direct  page.  At  present,  ACE 
uses  one  256-byte  page  of  bank  $00  memory  as  its  direct  page.  Future  versions  of  the  ACE 
tools  may  use  a  different  amount  of  memory  for  the  direct  page,  so  applications  should 
determine  the  correct  size  for  the  direct  page  with  a  call  to  ACEinf  o.  The  tool  set's  direct 
page  should  always  begin  on  a  page  boundary. 

Parameters 

Stack  before  call 


Previous  contents 


dPageAddr 


Word— Bank  $0  starting  address  of  direct-page  space 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1D01 
$1D02 


<— SP 

acelsActive 
aceBadDP 


ACE  Tool  Set  already  started  up. 
Requested  direct-page  location 
invalid. 


extern  pascal  void  ACEStartUp (dPageAddr) ; 
Word      dPageAddr; 
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ACEShutDown     $031D 

Performs  any  housekeeping  that  is  required  to  shut  down  the  ACE  Tool  Set.  Applications 
that  use  the  ACE  tools  should  always  make  this  call  before  quitting.  The  application,  not 
the  ACE  Tool  Set,  must  allocate  and  deallocate  direct-page  space  in  bank  zero. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1D03       aceNotActive  ACE  Tool  Set  not  started  up. 

C  extern  pascal  void  ACEShutDown ()  ; 
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ACEVersion     $04lD 


Returns  the  version  number  of  the  currently  installed  ACE  Tool  Set.  This  call  can  be  made 
before  a  call  to  ACEStartup.  The  versionlnfo  result  will  contain  the  information  in  the 
standard  format  defined  in  Appendix  A,  "Writing  Your  Own  Tool  Set,"  in  Volume  2  of  the 
Toolbox  Reference. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


versionlnfo 


Errors 
C 


None 


Word— Version  number  of  ACE  Tool  Set 
<— SP 


extern  pascal  Word  ACEVersion () ; 
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ACEReset    $051D 

Resets  the  ACE  Tool  Set.  This  call  is  made  by  a  system  reset. 

A  Warning       Applications  should  never  make  this  call  because  it 
performs  tool  set  initializations  appropriate  to  a 
machine  reset,  a 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  ACEReset (); 
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ACEStatus     $06lD 

Returns  a  Boolean  flag,  which  is  TRUE  (nonzero)  if  the  tool  set  has  been  started  up,  and 
FALSE  (zero)  if  it  has  not.  This  call  can  be  made  before  a  call  to  ACEStartup. 

♦   Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  ACEStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  the  ACE  Tool  Set  is  not  active,  the  returned  value  will  be 
FALSE  (NIL). 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


activeFlag 


Errors 
C 


Word— Boolean  value  indicating  whether  tool  set  is  active 
<— SP 

None 

extern  pascal  Word  ACEStatus  () ; 
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ACEInfo     $071D 

Returns  certain  information  about  the  currently  installed  version  of  the  ACE  tools.  This  call 
can  be  made  before  a  call  to  ACEStartup.  The  infoItemCode  parameter  specifies  what 
information  the  call  is  to  return.  At  present,  the  only  valid  value  is  0.  This  value  specifies 
that  the  call  will  return  the  size  in  bytes  of  the  direct  page  that  ACE  requires. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


infoItemCode 


Long— Space  for  result 

Word— What  type  of  information  to  return 
<— SP 


Stack  after  call 


Previous  contents 


-   infoItemValue  - 


Long— Requested  information 
<— SP 


Errors 


$1D04 


aceNoSuchParam 


Requested  information  type  not 
supported. 


extern  pascal  LongWord  ACEInfo (infoItemCode) ; 
Word      infoItemCode; 
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Audio  Compression  and  Expansion  tool  calls 

The  Audio  Compression  and  Expansion  tool  calls  are  all  new  calls,  added  to  the  Apple  IIGS 
Toolbox  since  the  first  two  volumes  of  the  Apple  IIGS  Toolbox  Reference  were  published. 


ACECoxnpBegin    $0B1D 

Prepares  the  ACE  tools  to  compress  a  new  audio  sequence.  After  ACECompress 
completes  the  process  of  compression  and  returns,  the  ACE  tools  normally  save  certain 
relevant  state  information  so  that  subsequent  calls  to  ACECompress  can  be  used  on 
succeeding  parts  of  the  same  audio  sequence.  It  is  often  desirable  to  break  a  long  audio 
signal  into  smaller  parts  for  compression.  The  preservation  of  appropriate  state  variables 
allows  a  call  to  ACECompress  to  compress  part  of  such  a  signal  and  then,  for  a 
subsequent  call,  to  continue  the  compression  process  where  the  previous  call  left  off. 

Just  before  a  program  calls  ACECompress  to  process  a  new  audio  sample,  it  should  call 
ACECompBegin  to  ensure  that  all  saved  state  information  is  cleared  and  that 
ACECompress  is  starting  with  a  "clean  slate."  When  an  application  is  compressing  a  long 
audio  sample  as  a  number  of  smaller  pieces,  it  should  call  ACECompBegin  only  before  the 
first  subsequence.  Thereafter,  the  application  should  not  make  this  call  until  all  parts  of 
the  sequence  have  been  processed.  The  state  information  that  ACE  preserves  between 
calls  allows  ACECompress  to  process  subsequent  blocks,  using  appropriate  information 
from  previous  ones. 

Call  ACECompBegin  only  before  compressing  the  first  sequence  of  a  series  of  sub- 
sequences, or  before  compressing  a  single  sequence  that  is  not  part  of  a  longer  sequence. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1D03       aceNotActive  ACE  Tool  Set  not  started  up. 

C  extern  pascal  void  ACECompBegin () ; 
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ACECompress     $091D 

Compresses  a  number  of  blocks  of  digital  audio  data-and  stores  the  compressed  data  at  a 
specified  location.  Each  input  block  contains  512  bytes  of  data  to  be  compressed.  Your 
program  also  specifies  the  compression  method,  using  the  method  parameter. 

Before  issuing  the  ACECompress  tool  call,  your  program  should  call  ACECompBegin  to 
prepare  the  ACE  Tool  Set  for  audio  compression. 


♦  Note:  Because  ACECompress  is  guaranteed  to  reduce  the  size  of  every  byte  of  source 
data,  the  resulting  data  can  be  stored  in  the  same  place  as  the  source  data.  That  is,  the 
source  and  destination  locations  in  RAM  can  be  the  same. 


Parameters 

Stack  before  call 


Previous  contents 


sre 


srcOffset 


dest 


destOjfset 


nBlks 


method 


Stack  after  call 


Long— Handle  to  the  source  data 

Long— Offset  from  sre  to  the  actual  storage  location 

Long— Handle  to  storage  for  the  resulting  data 

Long— Offset  from  dest  to  the  actual  storage  location 

Word— Number  of  51 2-byte  blocks  of  source  data 
Word— Method  of  compression 
<— SP 


Previous  contents 


Errors 


$1D05 

$1D06 
$1D07 
$1D08 


<— SP 

aceBadMethod 

aceBadSrc 

aceBadDest 

aceDataOverlap 


Specified  compression  method 
not  supported. 
Specified  source  invalid. 
Specified  destination  invalid. 
Specified  source  and  destination 
areas  overlap  in  memory. 
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C  extern  pascal  void  ACECompress (src,  srcOffset,  dest, 

destOffset,  nBlks,  method) ; 

Handle    src,  dest; 

Long      srcOffset,  destOffset; 

Word      nBlks,  method; 

src,  dest  Contain  handles  to  source  and  destination  data  locations, 

respectively. 

srcOffset,  destOffset  Contain  byte  offsets  from  locations  specified  by  src  and  dest, 

respectively.  These  parameters  allow  your  program  to  position  within 
an  input  sample  or  output  buffer. 

nBlks  Specifies  the  number  of  512-byte  blocks  of  audio  data  to  be 

compressed. 

method  Specifies  the  compression  method  to  be  used  by  ACECompress 

when  processing  the  data.  A  value  of  1  causes  each  byte  of  input  data 
to  be  compressed  to  a  4-bit  quantity;  a  value  of  2  yields  3  bits  per 
byte  of  input  data. 

Clearly,  the  value  of  the  method  parameter  helps  determine  the  size  of 
the  resulting  data  that  ACECompress  stores  at  destOffset  bytes 
beyond  the  location  specified  by  dest.  When  using  method  1  (4-bit 
compression),  you  can  calculate  the  number  of  bytes  ACECompress 
will  produce  by  multiplying  the  contents  of  the  nBlks  parameter  by  the 
number  of  bytes  in  a  data  block  (512),  multiplying  that  result  by  the 
number  of  result  bits  per  input  byte  (4),  and  then  dividing  by  the 
number  of  bits  in  a  byte  (8).  Expressed  as  a  formula,  the  calculation 
would  be 

((nBlks*  512)*  4)/ 8 

For  method  2,  the  same  basic  calculation  applies,  except  that  each 
input  byte  results  in  3  output  bits 

((nBlks*  512)*$/ 8 
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ACEExpand    $0A1D 

Expands  a  previously  compressed  audio  sample,  using  the  method  specified  by  the 
method  parameter,  and  stores  it  at  the  specified  location.  Unlike  ACECompress, 
ACEExpand  cannot  store  its  results  in  the  same  location  as  its  source  since  the  resulting 
data  is  2  to  2.67  times  as  large  as  the  source. 

Parameters 

Stack  before  call 


Previous  contents 


src 


srcOffset 


desl 


destOffset 


nBlks 


method 


Stack  after  call 


Long— Handle  to  the  source  data 

Long— Offset  from  src  to  the  actual  storage  location 

Long— Handle  to  storage  for  the  resulting  data 

Long — Offset  from  dest  to  the  actual  storage  location 

Word— Number  of  512-byte  blocks  to  be  stored  at  dest 
Word— Method  of  compression 
<— SP 


Previous  contents 


<— SP 
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Errors  $1D05       aceBadMethod  Specified  compression  method 

not  supported. 

$1D06       aceBadSrc  Specified  source  invalid. 

$1D07       aceBadDest  Specified  destination  invalid. 

$1D08       aceDataOverlap  Specified  source  and  destination 

areas  overlap  in  memory. 

C  extern  pascal  void  ACEExpand(src,  srcOffset,  dest, 

destOff set,  nBlks,  method) ; 

Handle    src,  dest; 

Long      srcOffset,  destOffset; 

Word      nBlks,  method; 

src,  dest  Contain  handles  to  source  and  destination  data  locations, 

respectively. 

srcOffset,  destOffset  Contain  byte  offsets  from  locations  specified  by  src  and  dest, 

respectively.  These  parameters  allow  your  program  to  position  within 
the  input  compressed  data  or  output  buffer. 

nBlks  Specifies  the  number  of  512-byte  blocks  of  expanded  data  to  be 

returned  at  the  location  destOffset  bytes  beyond  dest. . 

method  Specifies  the  method  used  when  the  sample  was  compressed.  A  value 

of  1  indicates  that  ACEExpand  is  to  expand  each  4-bit  quantity  in  the 
compressed  sample  into  an  8-bit  byte.  A  value  of  2  causes 
ACEExpand  to  process  3-bit  quantities  in  the  compressed  sample. 
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ACEExpBegin     $0C1D 

Prepares  ACE  to  expand  a  new  sequence.  Like  ACECompBegin,  ACEExpBegin  clears  any 
stored  state  information  from  previous  calls  to  expand  compressed  data.  You  can  expand 
a  large  compressed  sample  by  processing  it  as  a  series  of  subsequences  with  repeated  calls 
to  ACEExpand,  because  certain  appropriate  state  variables  are  preserved  from  call  to 
call.  If  you  are  calling  ACEExpand  to  work  on  a  new  sequence  that  bears  no  relation  to  any 
other  compressed  sequence,  or  to  expand  a  short  sequence  in  just  one  call  to 
ACEExpand,  you  should  make  this  call  first  to  clear  these  state  variables.  If,  on  the  other 
hand,  you  are  making  a  call  to  ACEExpand  to  expand  a  sequence  that  is  a  part  of  a  longer 
sequence  and  is  not  the  first  subsequence,  you  should  not  make  this  call  first,  because  it 
will  throw  away  all  information  that  ACE  has  recorded  about  the  previous  sequences. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1D03       aceNotActive  ACE  Tool  Set  not  started  up. 

C  extern  pascal  void  ACEExpBegin () ; 
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ACE  Tool  Set  error  codes 

This  section  lists  the  error  codes  that  may  be  returned  by  Audio  Compression  and  Expansion  Tool  Set 
calls. 

Value  Name  Definition 

ACE  Tool  Set  already  started  up. 

Requested  direct-page  location  invalid. 

ACE  Tool  Set  not  started  up. 

Requested  information  type  not  supported. 

Specified  compression  method  not  supported. 

Specified  source  invalid. 

Specified  destination  invalid. 

Specified  source  and  destination  areas  overlap 

in  memory. 


$1D01 

acelsActive 

$1D02 

aceBadDP 

$1D03 

aceNotActive 

$1D04 

aceNoSuchParam 

$1D05 

aceBadMethod 

$1D06 

aceBadSrc 

$1D07 

aceBadDest 

$1D08 

aceDataOverlap 
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Chapter  28   Control  Manager  Update 


This  chapter  documents  new  features  of  and  information  about  the 
Control  Manager.  The  complete  Control  Manager  documentation  is  in 
Volume  1,  Chapter  4  of  the  Toolbox  Reference. 
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Error  corrections 


This  section  documents  errors  in  Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox 
Reference. 

m   The  color  table  for  the  size  box  control  in  the  Toolbox  Reference  is  incorrect.  The 
correct  table  follows,  with  new  information  in  boldface. 


growOutline  word 
Bits  8-15 
Bits  4-7 
Bits  0-3 

growNorBack  word 
Bits  8-15 
Bits  4-7 
Bits  0-3 

growSelBack    word 
Bits  8-15 
Bits  4-7 
Bits  0-3 


Color  of  size  box's  outline 

-  zero 

=  outline  color 

*=  zero 

Color  of  interior  when  not  highlighted 

■  zero 

-  background  color 

-  icon  color 

Color  of  Interior  when  highlighted 

=  zero 

*  background  color 


=  Icon  color 

On  page  4-76  of  the  Toolbox  Reference,  in  the  section  that  covers  the  setctiParams 
call,  it  states  that  the  call  "Sets  new  parameters  to  the  control's  definition 
procedure . . ."  This  description  is  misleading;  the  call  does  not  direcdy  set  the 
parameters.  Rather,  it  sends  the  new  parameters  to  the  control's  definition  procedure, 
unlike  Setctivalue,  which  actually  sets  the  appropriate  value  in  the  control  record 
and  then  passes  the  value  on  to  the  definition  procedure. 
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Clarifications 


The  following  items  provide  additional  information  about  features  previously  described 
in  the  Toolbox  Reference. 

m   The  barArrowBack  entry  in  the  scroll  bar  table  was  never  implemented  as  first 
intended,  and  is  now  no  longer  used. 

■  The  Control  Manager  preserves  the  current  port  across  Control  Manager  calls,  including 
those  that  are  passed  through  other  tools,  such  as  the  Dialog  Manager. 

■  The  Control  Manager  preserves  the  following  fields  in  the  port  of  a  window  that 
contains  controls: 

bkPat  background  pattern 

pnLoc  pen  location 

pnsize  pen  size 

pnMode  pen  mode 

pnPat  pen  pattern 

pnMask  pen  mask 

pnvis  pen  visibility 
f  ontHandie     handle  of  current  font 

f  ontiD  ID  of  current  font 

f  ontFlags        font  flags 

txsize  text  size 

txFace  text  face 

txMode  text  mode 

spExtra  value  of  space  extra 

chExtra  value  of  character  extra 

f  gCoior  foreground  color 

bgcolor  background  color 

■  The  control  definition  procedures  for  simple  buttons,  check  boxes,  and  radio  buttons 
can  now  compute  the  size  of  their  boundary  rectangles  automatically.  The  computed 
size  is  based  on  the  size  of  the  title  string  for  the  button. 

■  To  ensure  predictable  color  behavior,  you  should  always  align  color  table-based 
controls  on  an  even  pixel  boundary  in  640  mode.  If  you  do  not  do  so,  the  control  will 
not  appear  in  the  colors  you  specify,  due  to  the  effect  of  dithering. 
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New  features  in  the  Control  Manager 

The  Control  Manager  now  supports  a  number  of  new  features.  This  section  discusses  these 
new  features  in  detail. 

Colors  in  control  tables  now  use  all  four  color  bits  in  both  modes;  they  formerly  used 
only  2  bits  in  640  mode.  This  change  affects  all  control  color  tables  defined  in  the 
Toolbox  Reference.  For  any  applications  that  use  color  controls  in  640  mode,  the  effect 
is  that  controls  will  be  a  different  color.  This  change  was  made  so  that  dithered  colors 
can  be  used  with  controls. 

The  scroll  bar  control  definition  procedure  now  maintains  the  required  relationship 
among  the  ctivalue,  viewsize,  and  datasize  fields  of  a  scroll  bar  record.  Prior 
to  Apple  IIGS  System  Software  5.0,  it  was  the  responsibility  of  the  application  to  ensure 
that  the  ctivalue  field  never  exceeded  the  difference  between  datasize  and 
viewsize  (datasize  -  viewsizej.  The  scroll  bar  control  definition  procedure  now 
adjusts  the  ctivalue  or  datasize  field  if  the  other  quantities  are  set  to  invalid 
values. 

For  example,  if  viewsize  -  30  and  datasize  - 100,  then  the  maximum  ctivalue 
allowed  is  70.  If  an  application  set  the  ctivalue  field  to  80,  the  Control  Manager 
would  adjust  datasizeto  110.  In  this  same  example,  if  ctivalue  -  70  and  the 
application  set  datasize  to  90,  the  Control  Manager  would  adjust  ctivalue  to  60. 

Changes  to  the  viewsize  field  can  also  invalidate  the  three  settings.  In  the  example 
mentioned  before,  in  which  ctivalue  -  70,  viewsize  -  30,  and  datasize  -  100, 
setting  viewsize  to  40  would  cause  Control  Manager  to  set  ctivalue  to  60. 


Keystroke  processing  in  controls 

Apart  from  the  normal  use  of  keystrokes  to  enter  data,  the  Control  Manager  now  supports 
two  special  uses  for  keyboard  data:  keystroke  equivalents  and  switching  between 
certain  types  of  controls. 
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Many  types  of  controls  support  keystroke  equivalents,  which  allow  the  user  to  select  the 
control  by  pressing  a  keyboard  key.  You  assign  a  keystroke  equivalent  for  a  control  in  its 
control  template  (see  "New  Control  Manager  templates  and  records"  later  in  this  chapter 
for  specifics  on  control  templates).  When  the  user  presses  that  key,  your  program  receives 
an  event  just  as  if  the  user  had  clicked  in  the  control.  Further,  the  system  will  automatically 
highlight  and  dim  the  control.  Note  that  this  feature  is  only  available  to  controls  that  have 
been  created  with  the  NewControi2  tool  call,  and  for  which  the  fctiwantsEvents  bit 
has  been  set  to  1  in  the  moreFiags  word  of  the  control  template.  See  "New  and  changed 
controls"  later  in  this  chapter  for  information  about  which  controls  support  keystroke 
equivalents. 

Edit  field  controls  (LineEdit  controls  and  TextEdit  controls)  accept  keystrokes  as  part  of 
their  normal  function.  Note,  however,  that  there  can  be  more  than  one  edit  field  control  in 
a  window.  Under  these  circumstances,  the  user  moves  among  these  controls  by  pressing 
the  Tab  key.  In  addition,  the  system  must  keep  track  of  which  control  is  meant  to  receive 
user  keystrokes.  To  do  so,  the  Control  Manager  now  supports  the  notion  of  a  target 
control.  The  target  control  is  that  edit  field  control  which  is  the  current  recipient  of  user 
actions  (keystrokes  and  menu  items). 


The  Control  Manager  and  resources 

You  can  now  specify  most  data  for  the  Control  Manager  using  either  pointers,  handles,  or 
resource  IDs  (see  "Chapter  45,  "Resource  Manager,""  in  this  book  for  complete 
information  on  resources).  Because  the  form  of  the  specification  may  differ,  the  Control 
Manager  (as  well  as  many  other  tool  sets)  also  requires  a  reference  type,  which  indicates 
whether  a  particular  reference  is  a  pointer,  handle,  or  resource  ID.  You  set  the  reference 
type  and  the  reference  as  appropriate  in  the  control  template  you  pass  to  the  Control 
Manager  NewControi2  tool  call. 

You  can  use  resources  to  store  a  wide  variety  of  items  for  the  Control  Manager.  For 
example,  the  tides  associated  with  simple  buttons,  radio  buttons,  and  check  boxes 
created  with  the  NewControi2  tool  call  may  be  stored  as  resources.  As  a  result,  your 
application  may  free  the  space  devoted  to  the  tide  string  after  the  control  has  been 
created.  Similarly,  you  can  define  control  definition  procedures  as  resources.  The  Control 
Manager  will  load  the  code  when  it  is  needed. 

The  Control  Manager  handles  resources  differently,  based  upon  the  data's  degree  of 
permanence.  For  temporary  information,  Control  Manager  loads  the  resource,  uses  the 
data,  and  then  frees  the  resource  (using  the  ReieaseResource  tool  call).  For  permanent 
information,  the  Control  Manager  loads  the  resource  each  time  the  resource  is  accessed.  • 
Such  resources  should  be  unlocked  and  unpurgeable. 
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The  current  version  of  the  Apple  IIGS  system  software  keeps  the  control  definition 
procedure  for  icon  button  controls  in  the  system  resource  file.  In  the  future,  the  sytsem 
may  store  other  defProcs  in  this  resource  file.  Consequently,  you  should  ensure  that  the 
Resource  Manager  can  reach  the  system  resource  file  in  any  resource  search  path  you  set  up 
(see  Chapter  45,  "Resource  Manager,"  later  in  this  book  for  more  information  on  the 
resource  file  search  path). 


New  and  changed  controls 

The  Control  Manager  now  supports  more  standard  control  types.  In  addition  to  the 
original  standard  controls  (buttons,  check  boxes,  radio  buttons,  size  boxes,  and  scroll 
bars),  the  Control  Manager  now  supports  the  following  controls: 

■  Static  text  controls  display  text  messages  in  a  rectangle  that  you  define.  The 
displayed  text  supports  word  wrap  and  character  styling.  This  text  cannot  be  edited 
by  the  user. 

■  Picture  controls  draw  a  picture  into  a  defined  rectangle. 

■  Icon  button  controls  allow  you  to  present  an  icon  as  part  of  a  button  control.  A 
defined  icon  is  displayed  within  the  bounds  of  the  rectangle  that  repiesents  the  button 
control  on  the  screen.  Icon  buttons  include  support  for  keyboard  equivalents. 

■  LineEdit  controls  allow  the  user  to  enter  single-line  items. 

■  TextEdit  controls,  supported  by  the  new  TextEdit  tool  set  (see 

Chapter  49,  TextEdit,"  in  this  book),  allow  the  user  to  edit  text  within  a  defined 
rectangle,  which  can  extend  beyond  a  single  line. 

■  Pop-up  menu  controls  support  scrolling  lists  of  possible  selection  options  that 
appear  when  the  user  selects  the  control. 

■  List  controls  display  scrollable  lists  of  items. 

In  order  to  create  any  of  these  new  controls,  you  must  set  up  the  appropriate  control 
template  and  call  NewControi2.  Unlike  the  NewControi  tool  call,  which  accepts  its 
control  definition  on  the  stack,  NewControi2  defines  controls  according  to  the 
contents  of  one  or  more  control  templates.  These  templates  contain  all  the  information 
necessary  for  the  Control  Manager  to  create  controls.  Your  application  fills  each  control 
template  with  the  data  appropriate  to  the  control  you  wish  to  create.  The  Control 
Manager  uses  this  input  specification  to  construct  the  corresponding  control  record  and 
create  the  control.  You  can  use  this  technique  to  create  any  control,  not  just  the  new 
control  types.  For  complete  information  on  the  format  and  content  of  these  control 
templates,  see  "New  Control  Manager  templates  and  records"  later  in  this  chapter. 
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All  controls  created  by  NewControi2,  rather  than  NewControi,  are  referred  to  as 
extended  controls.  Functionally,  extended  controls  do  not  differ  from  controls  created 
by  NewControi.  In  fact,  extended  control  records  will  work  with  all  Control  Manager  tool 
calls.  However,  the  control  record  for  an  extended  control  contains  more  data  than  the 
old-style  record.  In  addition,  many  new  Control  Manager  calls  and  features  are  valid  only 
for  extended  controls.  Note  that  any  control  created  by  NewControi2  is  an  extended 
control,  not  just  the  new  control  types.  For  complete  information  on  the  format  and 
content  of  extended  control  records,  see  "New  Control  Manager  templates  and  records" 
later  in  this  chapter. 

You  may  directly  call  NewControi2  or  you  may  invoke  it  indirectly  by  calling 

Newwindow2.  See  Chapter 45,  "Resource  Manager,"  and 

Chapter  52,  "Window  Manager  Update,"  for  details  on  new  window  calls. 

The  following  sections  discuss  each  type  of  control  supported  by  the  Control  Manager. 
For  the  original  controls,  these  sections  address  new  features  provided  by  the  Control 
Manager.  For  new  control  types,  these  sections  introduce  you  to  the  functionality  now 
provided. 


Simple  button  control 

Simple  button  controls  created  with  the  NewControi 2  tool  call  can  support  keystroke 
equivalents,  which  allow  the  user  to  activate  the  button  by  pressing  an  assigned  key  on  the 
keyboard.  See  "Keystroke  processing"  earlier  in  this  chapter  for  details. 

Check  box  control 

Check  box  controls  created  with  the  NewControi2  tool  call  can  support  keystroke 
equivalents,  which  allow  the  user  to  activate  the  box  by  pressing  an  assigned  key  on  the 
keyboard.  See  "Keystroke  processing"  earlier  in  this  chapter  for  details. 

Icon  button  control 

This  new  type  of  control  can  display  an  icon  as  well  as  text  in  a  defined  window.  You 
specify  the  boundary  rectangle  for  the  window  and  a  reference  to  the  icon  when  you 
create  the  control  (see  Chapter  17,  "QuickDraw  II  Auxiliary,"  in  Volume  2  of  the  Toolbox 
Reference  for  information  about  icons).  You  can  create  icon  button  controls  only  with  the 
NewControi 2  tool  call. 
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Icon  button  controls  operate  much  like  simple  button  controls.  Note,  however,  that  with 
icon  controls,  the  control  rectangle  is  inset  slightly  from  its  specified  coordinates  before 
the  button  is  drawn.  As  a  result,  outlined  round  buttons  stay  completely  within  the 
specified  control  rectangle  (this  is  not  the  case  for  an  outlined  round  simple  button 
control).  Icon  button  controls  support  keyboard  equivalents  (see  "Keystroke  processing" 
earlier  in  this  chapter  for  details). 

The  icon  is  drawn  each  time  the  control  is  drawn.  The  icon  and  text  are  centered  in  the 
specified  control  rectangle.  If  the  control  has  no  text,  the  icon  is  still  centered.  The  icon  is 
not  clipped  to  the  control  rectangle.  If  the  icon  is  larger  than  the  specified  control 
rectangle,  then  when  you  erase  the  control,  that  portion  of  the  icon  that  lay  outside  the 
rectangle  will  not  be  erased. 

Note  that  icon  controls  require  the  QuickDraw  II  Auxiliary  and  Resource  Manager  tool 
sets.  Note  as  well  that  the  control  definition  procedure  for  icon  buttons  is  kept  in  the 
system  resources  file. 

LineEdit  control 

This  new  control  type  lets  your  application  manage  single-line,  editable  items  in  a  window. 
You  specify  the  boundary  rectangle  for  the  text,  the  maximum  number  of  characters 
allowed,  and  an  initial  value  for  the  displayed  text  string  when  you  create  the  control  with 
the  NewControi2  tool  call.  The  text  is  updated  each  time  the  control  is  drawn.  LineEdit 
controls  also  support  password  fields,  which  do  not  echo  the  characters  entered  by  the 
user.  Rather,  the  control  echoes  each  typed  character  as  an  asterisk. 

LineEdit  controls  respond  to  both  mouse  and  keyboard  events.  If  your  application  uses 
TaskMaster,  the  system  will  handle  most  events  automatically.  To  take  full  advantage  of 

TaskMaSter,  set  the  tmContentControls,  tmControlKey,  and  tmldleEvents  flags 

in  the  taskMask  field  of  the  task  record  to  1  (see 

Chapter  52,  "Window  Manager  Update,"  for  information  about  the  new  features  in 

TaskMaster). 

If  your  application  does  not  use  TaskMaster,  when  the  user  presses  the  mouse  button  in  a 
LineEdit  control  your  application  must  call  Trackcontroi  to  track  the  mouse  and 
perform  appropriate  text  selection.  TaskMaster  will  do  this  automatically  if  you  have  set 
the  tmContentControls  flag  to  1  in  the  taskMask  field  of  the  task  record. 
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Without  TaskMaster,  your  application  sends  keyboard  events  to  LineEdit  controls  using 
the  SendEventToCti  tool  call  (see  "New  Control  Manager  calls"  later  in  this  chapter). 
First,  your  code  must  check  for  menu  key  equivalents.  If  none  are  found,  then  issue  the 
SendEventToCti  call,  setting  targetoniyFlag  to  FALSE  (all  controls  that  want 
events  are  searched),  windowPtr  to  NIL  (find  the  top  window),  and 
extendedTaskRecPtr  to  refer  to  the  task  record  containing  the  keystroke 
information.  Again,  TaskMaster  will  do  all  this  for  you  if  you  have  set  the  tmControiKey 
flag  to  1  in  the  taskMask  field. 

To  keep  the  caret  flashing,  your  application  must  send  idle  events  to  the  LineEdit  control. 
In  order  to  do  this,  issue  a  SendEventToCti  call,  setting  targetOnlyFlag  to  TRUE 
(send  event  only  to  target  control),  windowPtr  to  NIL  (use  top  window),  and 
extendedTaskRecPtr  to  refer  to  the  task  record  containing  the  event  information. 
TaskMaster  will  do  this  for  you  if  you  have  set  the  tmidieEvents  flag  to  1  in  the 
taskMask  field. 

The  LineEdit  tool  set  performs  line  editing  in  LineEdit  controls.  If  you  want  to  issue 
LineEdit  tool  calls  directly  from  your  program,  retrieve  the  LineEdit  record  handle  from 
the  ctiData  field  of  the  control  record  for  the  LineEdit  control. 

List  control 

This  new  control  type  allows  your  program  to  display  lists  from  which  the  user  may  select 
one  or  more  items.  You  have  the  benefit  of  full  List  Manager  functionality,  with  respect  to 
such  features  as  selection  window  scrolling  and  item  selection  (single  item,  arbitrary 
items,  or  ranges).  You  specify  the  parameters  for  the  list  as  well  as  the  initial  conditions 
for  its  display  when  you  define  the  control.  The  Control  Manager  and  the  List  Manager 
take  care  of  the  rest.  You  can  create  list  controls  only  with  the  NewControi2  tool  call. 

List  controls  use  the  List  Manager  tool  set.  In  order  to  understand  how  to  use  this  control 
in  your  application,  see  Chapter  11,  "List  Manager,"  in  Volume  1  of  the  Toolbox  Reference. 


Picture  control 

This  new  control  type  displays  a  QuickDraw  picture  in  a  specified  window.  You  specify 
the  boundary  rectangle  for  the  control  and  a  reference  to  the  picture  when  you  create  the 
control.  The  picture  is  drawn  each  time  the  control  is  drawn.  You  can  create  picture 
controls  only  with  the  NewControi2  tool  call. 
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Note  that  when  the  picture  is  drawn,  the  boundary  rectangle  for  the  control  is  used  as  the 
picture  destination  rectangle  (see  Chapter  17,  "QuickDraw  II  Auxiliary,"  in  Volume  2  of 
the  Toolbox  Reference  for  details  about  picture  drawing).  As  a  consequence,  the  picture 
may  be  scaled  at  draw  time  if  the  original  picture  frame  does  not  have  the  same 
dimensions  as  the  control  rectangle.  To  force  the  picture  to  be  displayed  at  its  original 
size,  and  thus  avoid  scaling,  set  the  lower-right  corner  of  the  control  rectangle  to  (0,0). 
The  Control  Manager  recognizes  this  value  at  control  initialization  time,  and  sets  the 
control  rectangle  to  be  the  same  size  as  the  picture  frame. 

In  general,  a  click  in  a  picture  control  is  ignored.  However,  the  Control  Manager  provides 
facilities  to  inform  your  application  if  the  user  clicks  in  the  control.  To  make  a  picture 
control  inactive,  set  the  ctiHiiite  field  to  $FF,  otherwise  the  control  is  active  and  may 
receive  user  events. 

Note  that  picture  controls  require  the  QuickDraw  II  Auxiliary  tool  set. 

Pop-up  control 

This  new  control  type  allows  you  to  define  and  support  pop-up  menus  inside  a  window. 
You  specify  the  boundary  rectangle  for  the  control,  along  with  a  reference  to  the  menu 
definition  when  you  create  the  control  with  the  NewControi2  tool  call.  The  menu  tide 
becomes  the  tide  of  the  control,  and  the  current  selection  for  the  control  is  defined  by  the 
initial  value. 

Pop-up  controls  respond  to  both  mouse  and  keyboard  events.  If  your  application  uses 
TaskMaster,  the  system  will  handle  most  events  automatically.  To  take  full  advantage  of 

TaskMaster,  set  the  tmContentControls  and  tmControlKey  flags  in  the  taskMask 
field  of  the  task  record  to  1  (see  Chapter  52,  "Window  Manager  Update,"  for  information 
about  the  new  features  in  TaskMaster). 

If  your  application  does  not  use  TaskMaster,  when  the  user  presses  the  mouse  button 
inside  a  Pop-up  control,  your  application  must  call  Trackcontroi  to  track  the  mouse 
and  present  the  pop-up  menu  to  the  user.  TaskMaster  will  do  this  for  you  if  you  have  set 
the  tmContentControls  flag  tO  1  in  the  taskMask  field. 

Without  TaskMaster,  your  program  sends  keyboard  events  to  pop-up  menu  controls  using 
the  SendEventToCtl  tool  call  (see  "New  Control  Manager  calls"  later  in  this  chapter). 
First,  check  for  menu  key  equivalents.  If  none  are  found,  then  issue  the 
SendEventToCtl  call,  setting  targetOnlyFlag  to  FALSE  (all  controls  that  want 
events  are  searched),  windowptr  to  NIL  (find  the  top  window),  and 
extendedTaskRecPtr  to  refer  to  the  task  record  containing  the  keystroke 
information.  TaskMaster  will  do  all  this  for  you  if  you  have  set  the  tmControlKey  flag  to 
1  in  the  taskMask  field. 
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Note  that  the  Control  Manager  places  the  current  user  selection  value  into  ctivaiue.  If 
you  need  to  retrieve  the  user  selection  number,  you  may  do  so  from  this  field. 

Radio  button  control 

Radio  button  controls  created  with  the  NewControi2  tool  call  can  support  keystroke 
equivalents,  which  allow  the  user  to  choose  a  button  by  pressing  an  assigned  key  on  the 
keyboard.  See  "Keystroke  processing"  earlier  in  this  chapter  for  details. 

Scroll  bar  control 

Scroll  bar  controls  provide  no  new  features. 

Size  box  control 

You  can  now  set  up  size  box  controls  to  automatically  invoke  Growwindow  and 
sizewindow  if  you  create  the  control  with  the  NewControi2  tool  call.  When  the  user 
drags  the  size  box,  if  the  f  CaiiwindowMgr  bit  in  the  flag  field  of  the  size  box  control 
template  is  set  to  1  (see  the  description  of  the  size  box  control  template  in  "New  Control 
Manager  templates  and  records"  later  in  this  chapter),  the  Control  Manager  will  call 
Growwindow  and  sizewindow  to  track  the  control  and  resize  the  window  rectangle.  If 
this  flag  is  set  to  0,  then  the  control  is  merely  highlighted. 

Static  text  control 

This  new  control  type  displays  uneditable  (hence,  "static")  text  in  a  specified  window. 
You  can  place  font,  style,  size,  and  color  changes  into  the  displayed  text,  affording  you 
great  freedom  to  create  a  distinctive  text  display.  In  addition,  static  sext  controls  can 
accommodate  text  substitution.  With  this  feature,  you  can  customize  the  displayed  text 
to  fit  run-time  circumstances.  You  can  create  static  text  controls  only  with  the 
NewControl2  tool  call. 

If  you  are  going  to  use  text  substitution  in  your  static  text,  your  application  must  set  up 
the  control  template  correctly  (set  f  SubstituteText  in  flag  to  1)  and  tell  the  system 
where  the  substitution  array  is  kept  (issue  the  setctiParamPtr  Control  Manager  tool 
call).  The  text  substitution  array  has  the  same  format  as  that  used  by  the  Alertwindow 
call  (see  Chapter  52,  "Window  Manager  Update,"  for  information  about  Alertwindow 
and  for  substitution  array  format  and  content). 
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In  general,  applications  ignore  clicks  in  static  text  controls.  However,  the  Control 
Manager  provides  facilities  to  inform  your  application  if  the  user  clicks  in  the  control.  To 
make  a  static  text  control  inactive,  set  the  ctiHiiite  field  to  $FF,  otherwise  the 
control  is  active  and  may  receive  user  events. 

Note  that  static  text  controls  require  the  LineEdit,  QuickDraw  II  Auxiliary,  and  Font 
Manager  tool  sets. 

TextEdit  control 

This  control  lets  the  user  create,  edit,  or  view  multiline  items  in  a  window.  You  specify  the 
boundary  rectangle  for  the  edit  window,  parameters  governing  the  amount  of  text  to  be 
entered,  and,  optionally,  some  initial  text  to  display.  The  TextEdit  control  does  the  rest. 
You  can  only  create  TextEdit  controls  with  the  NewControi2  tool  call. 

The  TextEdit  control  uses  the  TextEdit  tool  set.  TextEdit  is  a  new  tool  set,  and  is 
completely  described  in  Chapter  49,  "TextEdit,"  later  in  this  book.  You  should  familiarize 
yourself  with  the  material  in  that  chapter  before  using  this  control. 


New  control  definition  procedure  messages 

Previously,  control  definition  procedures  had  to  support  13  message  types  (see 
Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for  a  discussion  of  the 
original  message  types).  When  you  create  custom  controls  with  new  control  records  (see 
"New  Control  Manager  templates  and  records"  later  in  this  chapter),  your  control  will  have 
to  support  some  additional  messages. 


Value 

Control  Message     Description 

13 

ctlHandleEvent 

Handle  a  keystroke  or  menu  selection 

14 

ctlChangeTarget 

Issued  when  control's  target  status  has 
changed 

15 

ctlChangeBounds 

Issued  when  control's  boundary 
rectangle  has  changed 

16 

ctlWindChangeSize 

Window  has  been  grown  or  zoomed 

17 

ctlHandleTab 

Control  has  been  tabbed  to 

18 

ctlNotifyMultiPart 

A  multipart  control  must  be  hidden, 
drawn,  or  shown 

19 

ctlWinStateChange 

Window  state  has  changed 
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In  addition,  the  initcti,  dragCnti,  and  recsize  messages  have  new  control  routine 
interfaces  when  used  with  extended  controls.  The  following  sections  discuss  each  new  or 
changed  message  in  detail. 

If  you  must  draw  when  handling  control  messages,  your  control  definition  procedure 
should  save  the  current  GrafPort  and  set  the  port  correctly  for  your  control  before 
drawing.  After  your  defProc  is  finished  drawing,  restore  the  previous  GrafPort.  Note  that 
saving  the  current  GrafPort  includes  saving  penstate,  all  pattern  and  color  information, 
and  all  regions  in  the  port  to  which  your  program  draws. 

To  maintain  compatibility  with  future  versions  of  the  Control  Manager,  control  definition 
procedures  should  always  return  a  retValue  of  0  for  unrecognized  and  unsupported  control 
message  types.  In  addition,  if  you  use  custom  control  messages,  be  careful  to  assign  type 
values  greater  than  $8000  (decimal  32,767). 

Initialize  routine 

Previously,  ctlParam  contained  paraml  and param2 from  Newcontroi.  If  you  create 
your  custom  control  with  Newcontroi,  these  input  parameters  are  the  same.  However,  if 
you  create  your  control  with  NewControi2  (see  "New  Control  Manager  calls"  later  in  this 
chapter),  then  ctlParam  contains  a  pointer  to  the  control  template  for  the  control. 

Drag  routine 

The  result  code  for  the  drag  routine  now  contains  additional  information  that  allows 
control  definition  procedures  to  abort  tracking.  Previously,  retValue  indicated  whether  or 
not  your  defProc  wanted  the  Control  Manager  to  do  the  dragging.  For  controls  created 
with  Newcontroi,  this  is  still  the  case.  For  controls  created  with  NewControi2,  your 
defProc  uses  the  low-order  word  of  retValue  exactly  as  before  (zero  means  that  the 
Control  Manager  should  drag  the  control;  nonzero  means  your  control  definition 
procedure  handled  it).  Your  defProc  returns  the  part  code  of  the  control  in  the  high-order 
word  (see  Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for 
information  on  control  part  codes).  If  this  value  is  0,  then  the  Control  Manager  assumes 
that  the  user  aborted  the  drag  operation  and  performs  no  screen  updates. 

Record  size  routine 

Previously,  ctlParam  was  undefined  for  this  routine.  Now,  the  Control  Manager  sets 
ctlParam  to  0  for  controls  created  with  Newcontroi.  For  controls  created  with 
NewControi2,  ctlParam  contains  a  pointer  to  the  control  template. 
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Event  routine 

To  pass  information  for  all  events,  including  keystroke  or  mouse  events,  the  Control 
Manager  calls  the  control  definition  procedure  with  the  ctiHandieEvent  message.  Only 
controls  you  create  with  either  the  f  ctiwantsEvents  bit  or  the  f  ctiCanBeTarget 
bit  set  to  1  in  the  moreFiags  field  of  the  control  template  will  receive  this  message  (see 
"New  Control  Manager  templates  and  records"  later  in  this  chapter  for  detailed 
information  on  these  flags).  The  first  qualifying  control  in  the  control  list  gets  the  first 
opportunity  to  handle  the  event.  If  that  control  processes  the  event,  then  no  other 
controls  see  it  If,  however,  that  control  does  not  process  the  event,  the  Control  Manager 
passes  the  event  to  the  next  qualifying  event  in  the  list.  This  process  continues  until  a 
control  handles  the  event,  or  the  list  is  exhausted.  If  no  defProc  handles  the  event, 
TaskMaster  passes  the  event  to  the  application. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Stack  after  call 


Long— Space  for  result 

Word— ctiHandieEvent  message 

Long— Pointer  to  task  record  containing  event  information 

Long— Handle  to  control 
<— SP 


Previous  contents 


retValue 


Long— $FFFFFFFF  if  control  took  the  event;  $0  if  control  did  not 
<— SP 
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Target  routine 

To  signal  a  change  in  the  control's  target  status  (the  control  is  now,  or  is  no  longer,  the 
target),  the  Control  Manager  calls  the  control  definition  procedure  with  the 
ctichangeTarget  message.  Note  that  this  message  is  sent  to  both  the  previous  target 
control  and  the  new  target  control.  Your  control  definition  procedure  can  distinguish 
which  control  is  the  new  target  by  examining  the  f  ctiTarget  bit  in  the  ctiMoreFiags 
field  of  the  control  record.  The  new  target  control  will  have  this  bit  set  to  1  in  its  control 
record.  The  previous  target  will  have  the  bit  set  to  0. 

In  response  to  the  ctichangeTarget  message,  some  control  definition  procedures  will 
change  the  appearance  of  their  control  on  the  screen  or  perform  other  actions  as 
appropriate.  For  example,  LineEdit  and  TextEdit  controls  display  an  insertion  point  or  a 
text  selection  only  when  they  are  the  target. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Long— Space  for  result 

Word— ctichangeTarget  message 

Long— Undefined 

Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


retValue 


Long— Undefined 
<— SP 
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Bounds  routine 

To  signal  to  the  control  that  its  boundary  rectangle  has  changed  the  Control  Manager  calls 
the  control  definition  procedure  with  the  ctichangeBounds  message.  In  response  to 
this  message,  your  control  definition  procedure  should  adjust  its  internal  control  record 
variables  to  account  for  the  new  rectangle.  For  example,  any  subrectangles  defined  for  a 
control  may  need  to  change  whenever  the  boundary  rectangle  changes. 

♦   Note:  This  message  is  not  supported  by  control  definition  procedures  currently 
provided  by  Apple;  however,  you  should  handle  this  message  in  any  custom  controls 
you  create. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Long— Space  for  result 

Word — ctichangeBounds  message 

Long— Undefined 

Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


retValue 


Long— Undefined 
<— SP 


28-16     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Window  size  routine 

The  Control  Manager  calls  the  control  definition  procedure  with  the 
etiwindchangesize  message  whenever  the  user  has  changed  the  size  of  the  control 
window.  In  response  to  this  message,  your  control  definition  procedure  should  do  what  is 
necessary  to  maintain  a  consistent  screen  presentation.  This  may  entail  resizing  multipart 
controls,  moving  size  boxes,  and  so  on. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Stack  after  call 


Long— Space  for  result 

Word— ctlWindChangeSize  message 

Long— Undefined 

Long— Handle  to  control 

<— SP 


Previous  contents 


retValue 


Long— Undefined 
<— SP 


Chapter  28    Control  Manager  Update     28-17 


Apple  1IGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Tab  routine 

Your  control  definition  procedure  receives  the  ctiHandieTab  message  when  the  user 
has  hit  the  Tab  key  while  another  control  is  the  target.  That  control's  defProc  will  have 
issued  the  MakeNextctiTarget  tool  call  before  sending  this  control  message.  As  a 
result,  your  control  is  the  target  control.  The  control  definition  procedure  should  perform 
the  appropriate  actions  in  response  to  becoming  the  target  as  a  result  of  a  Tab  keystroke, 
rather  than  a  mouse  click.  For  example,  in  response  to  this  message,  LineEdit  and 
TextEdit  control  definition  procedures  select  all  the  text  in  the  control  in  preparation  for 
user  input 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Stack  after  call 


Long— Space  for  result 

Word— ctiHandieTab  message 

Long— Undefined 

Long— Handle  to  control 
<— SP 


Previous  contents 


retValue 


Long— Undefined 
<— SP 
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Notify  multipart  routine 

The  Control  Manager  calls  the  control  definition  procedure  with  the 
ctiNotif  yMuitiPart  message  to  signal  that  a  multipart  control  needs  to  be  hidden, 
shown,  or  drawn.  This  message  is  relevant  only  to  multipart  controls,  which  may  not  fit 
within  their  boundary  rectangle  (for  example,  list  controls  consist  of  the  list  itself  and  a 
scroll  control,  which  is  separate).  That  is,  the  f  ctiisMuitiPart  bit  in  the  moreFiags 
field  of  the  control  template  must  be  set  to  1  for  a  control  to  receive  this  message.  In 
response  to  this  message,  your  defProc  must  do  what  is  needed  to  hide  or  show  the 
control  completely. 

The  low-order  word  of  ctlParam  tells  the  defProc  what  to  do. 

0  Hide  the  entire  control 

1  Erase  the  entire  control 

2  Show  the  entire  control 

3  Show  one  control 

Parameter 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Stack  after  call 


Long— Space  for  result 

Word— ctiNotif  yMuitiPart  message 

Long— High-word  is  undefined;  low-word  contains  option 

Long— Handle  to  control 
<— SP 


Previous  contents 


retValue 


Long— Undefined 
<— SP 
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Window  change  routine 

The  Control  Manager  calls  the  control  definition  procedure  with  the 
ctiwinstatechange  message  to  signal  that  the  state  of  the  window  containing  the 
control  has  changed.  For  example,  a  control  definition  procedure  will  receive  this  message 
whenever  the  control's  window  is  activated  or  deactivated.  At  this  time,  the  control 
definition  procedure  may  draw  dimmed  controls  in  windows  that  have  been  unhidden. 

The  low-order  word  of  the  ctlParam  parameter  contains  the  new  state  of  the  window: 

$0000    The  window  has  been  deactivated 
$0001    The  window  has  been  activated 

I  The  high-order  word  is  undefined. 

Parameter 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Long— Space  for  result 

Word — ctlWinStateChange  message 

Long— Low  word  contains  new  window  state;  high  word  undefined 

Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


retValue 


Long— Undefined 
<— SP 
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New  Control  Manager  calls 

The  following  sections  describe  new  Control  Manager  tool  calls,  in  alphabetical  order  by 
call  name. 


CallCtlDefProc     $2C10 


This  routine  calls  the  specified  control  with  the  specified  control  message  and  parameter. 
Set  the  param  parameter  to  0  if  the  control  definition  procedure  does  not  accept  an  input 
parameter  (see  "New  control  definition  procedure  messages"  earlier  in  this  chapter  for 
information  on  input  parameters  for  defProc  messages). 


Parameters 

Stack  before  call 


Previous  contents 


Space 


-      ctlHandle 


message 


param 


Stack  after  call 


Long— Space  for  result  from  control  definition  procedure 

Long— Handle  of  control  to  be  called 
Word— Control  message  to  send  to  control  definition  procedure 
Long— Parameter  to  pass  to  control  definition  procedure 
<— SP 


Previous  contents 


Result 


Errors 


None 


Long— Result  value  from  control  definition  procedure 
<— SP 
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extern  pascal  Long  CallCtlDefProc (ctlHandle, 
message,  param) ; 


Handle 

ctlHandle; 

Word 

message; 

Long 

param; 
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CMLoadResource     $3210 

This  is  an  entry  point  to  the  internal  Control  Manager  routine  that  loads  resources.  You 
specify  the  resource  type  and  ID  of  the  resource  to  be  loaded.  See 
Chapter  45,  "Resource  Manager,"  for  more  information  on  resources. 

Any  errors  during  resource  load  result  in  system  death. 


A  Warning       Applications  must  never  issue  this  call. 


Parameters 

Stack  before  call 

Previous  contents 

Space 

Long— Space  for  result 

resourceType 

Word— Type  of  resource  to  load 

resourcelD 

Long— ID  of  resource  to  load 

<— SP 

Stack  after  call 

Previous  contents 

-  resourceHandle  - 

Long— Handle  of  loaded  resource 

<— SP 

Errors                  None 

C                             exte 

rn  pascal   Handle  CMLoadResourc 

resourcelD) ; 

Word 

resourceType; 

Long 

resourcelD; 
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CMReleaseResource     $3310 

This  is  an  entry  point  to  the  internal  Control  Manager  routine  that  releases  resources.  You 
specify  the  resource  type  and  ID  of  the  resource  to  be  released.  The  resource  is  released 
by  marking  it  purgeable.  See  Chapter  45,  "Resource  Manager,"  for  more  information  on 
resources. 


Any  errors  result  in  system  death. 


A  Warning       Applications  must  never  issue  this  call. 


Parameters 

Stack  before  call 

Previous  contents 

resourceType 

Word— Type  of  resource  to  release 

resourcelD 

Long— ID  of  resource  to  release 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C                              exte 

rn  pascal  void  CMReleaseResourc 

resourcelD) ; 

Word 

resourceType ; 

Long 

resourcelD; 
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FindTargetCtl     $2610 

Searches  the  control  list  for  the  active  window  and  returns  the  handle  of  the  target  control 
(the  control  that  is  currently  the  target  of  user  keystrokes).  FindTargetCtl  returns  the 
handle  of  the  first  control  that  has  the  f  ctiTarget  flag  set  to  1  in  the  ctiMoreFiags 
field  of  its  control  record.  If  no  target  control  is  found  or  an  error  occurs,  then  the  call 
returns  a  NIL  handle. 

This  call  will  only  return  a  handle  to  an  extended  control. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


Result 


Errors 


Long— Handle  of  target  control  (if  found);  NIL  if  none  or  error 
<— SP 


$1004 

noCtlError 

No  controls  in  window 

$1005 

noSuperCtlError 

No  extended  controls  in  window 

$1006 

noCtlTargetError 

No  target  extended  control 

$100C 

noWind  Err 

No  front  window 

extern  pascal  Handle  FindTargetCtl () ; 
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GetCtlHandleFromID     $3010 

Retrieves  the  handle  to  the  control  record  for  a  control  with  a  specified  ctiiD  field  value. 
The  ctiiD  field  is  an  application-defined  tag  for  a  control.  Set  the  ctiiD  field  with  the 
setctiio  tool  call;  read  the  contents  of  the  ctiiD  field  with  GetctiiD. 

If  an  error  occurs,  the  returned  handle  is  NIL. 

(This  call  is  valid  only  for  extended  controls. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


-     windowPtr 


ctiiD 


Long— Space  for  result 

Long— Pointer  to  window  for  control  list  search;  NIL=top  window 

Long— ID  value  for  desired  control 
<— SP 


Stack  after  call 


Previous  contents 


ctlHandle      - 


Long— Handle  for  specified  control 
<— SP 


Errors 


$1004 

noCtlError 

No  controls  in  window 

$1005 

noSuperCtlError 

No  extended  controls  in  window 

$1009 

noSuchlDError 

The  specified  ID  cannot  be 
found 

$100C 

noWind  Err 

There  is  no  front  window 

extern  pascal  Long  GetCtlHandleFromID (windowPtr, 
ctiiD) ; 

Pointer   windowPtr; 
Long      ctiiD; 
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GetCtllD     $2A10 


Returns  the  ctiiD  field  from  the  control  record  of  a  specified  control.  The  ctiiD  field  is 
an  application-defined  tag  for  a  control.  Your  application  can  use  this  field  in  many  ways. 
For  example,  since  the  value  of  ctiiD  is  known  at  compile  time,  you  can  construct 
efficient  routing  code  for  handling  control  messages  for  many  different  controls. 

Use  the  setctiiD  Control  Manager  tool  call  to  set  the  eti id  field. 

If  the  specified  control  is  not  an  extended  control,  the  resulting  ID  is  undefined,  and  an 
error  is  returned. 


Pan 

Stac 

imeters 

k  before  call 

Previous  contents 

• 

Space 

Long— Space  for  result 

ctlHandle     - 

Long— Handle  to  control 

Stac 

k  after  call 
Previous  contents 

<— SP 

ctllD 

Long— ctiiD  for  specifi 

Em 

ore                  $10W 
$100" 

<— SP 

noCtlError 
notSuperCtlError 

No  controls  in  window 
Action  valid  only  for  extended 
controls 


extern  pascal  Long  GetCtllD (ctlHandle) ; 
Handle  ctlHandle; 
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GetCtlMoreFlags     $2E10 

Gets  the  contents  of  the  ctiMoreFiags  field  of  the  control  record  for  a  specified 
control.  The  ctiMoreFiags  field  contains  flags  governing  target  status,  event 
processing,  and  other  aspects  of  the  control. 

Use  the  setctiMoreFiags  Control  Manager  tool  call  to  set  the  ctiMoreFiags  field. 

If  the  specified  control  is  not  an  extended  control,  the  result  is  undefined,  and  an  error  is 
returned. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlHandle      - 


Word— Space  for  result 
Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


ctiMoreFiags 


Errors 


Word— ctiMoreFiags  for  specified  control 
<-SP 

$1004        noCtiError  No  controls  in  window 

$1007        notSuperCtiError        Action  valid  only  for  extended 

controls 

extern  pascal  Word  GetCtlMoreFlags (ctlHandle) ; 
Handle    ctlHandle; 
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GetCtlParamPtr     $3510 

Retrieves  the  pointer  to  the  current  text  substitution  array  for  the  Control  Manager.  This 
array  contains  the  information  used  for  text  substitution  in  static  text  controls  (see 
"Static  text  control"  elsewhere  in  this  chapter  for  details). 

Set  the  contents  of  this  field  with  the  SetctiParamPtr  Control  Manager  tool  call. 


♦    Note:  This  pointer  is  global  to  the  Control  Manager;  it  is  not  associated  with  a  specific 
control.  As  a  result,  desk  accessories  should  be  very  careful  when  using  this  feature  to 
save  and  restore  the  previous  contents  of  the  field. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Long— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


-    subArrayPtr    - 


Errors 
C 


None 


Long— Pointer  to  text  substitution  array 
<— SP 


extern  pascal  Pointer  GetCtlParamPtr () ; 
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InvalCtls     $3710 

This  call  invalidates  all  rectangles  for  all  controls  in  a  specified  window. 

Parameters 

Stack  before  call 


Previous  contents 


-     windowPtr     - 


Stack  after  call 


Long— Pointer  to  window  for  operation 
<— SP 


Previous  contents 


Errors 
C 


<— SP 
None 

extern  pascal  void  InvalCtls (windowPtr) 
Pointer   windowPtr; 
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MakeNextCtlTarget     $2710 

Makes  the  next  eligible  control  the  target  control.  This  routine  searches  the  control  list  of 
the  active  window  for  the  first  target  control  (f  ctiTarget  bit  on  in  the 
ctiMoreFiags  field  of  the  control  record).  It  then  clears  the  target  flag  for  this  control, 
and  searches  for  the  next  control  in  the  control  list  that  can  be  the  target 
(fctiCanBeTarget  bit  set  to  1  in  ctiMoreFiags),  and  makes  that  control  the  target. 
The  call  returns  the  handle  of  the  new  target  control. 

Both  affected  controls  (the  old  and  new  target)  will  receive  ctiChangeTarget 
messages  from  the  Control  Manager. 

If  an  error  occurs,  the  returned  handle  is  NIL 

This  call  is  valid  only  for  extended  controls. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result  (handle) 
<— SP 


Previous  contents 


Result 


Errors 


$1004 
$1005 
$100B 


Long— Handle  of  new  target  control;  NIL  if  error 
<— SP 

noctiError  No  controls  in  window 

noSuperctiError  No  extended  controls  in  window 

noCtlToBeTargetError 

No  control  could  be  made  target 


extern  pascal  Handle  MakeNextCtlTarget 0 ; 
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MakeThisCtlTarget     $2810 

This  routine  makes  the  specified  control  the  target.  You  specify  the  control  that  is  to 
become  the  target  control  by  passing  its  handle  to  this  routine.  This  call  will  work  for  both 
active  and  inactive  windows. 

Both  affected  controls  (the  old  and  new  target)  will  receive  ctichangeTarget 
messages  from  the  Control  Manager. 

I  This  call  is  valid  only  for  extended  controls. 
Parameters 
Stack  before  call 


Previous  contents 


-   ctlToBeTarget   - 


Long— Handle  to  control  to  be  made  target 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1007 


<— SP 
notSuperCtlError 


Action  valid  only  for  extended 
controls 
$1008        canNotBeTargetError  Specified  control  cannot  be 

made  target 

extern  pascal  void  MakeThisCtlTarget (CtlToBeTarget)  ; 
Handle    ctlToBeTarget; 
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NewControl2     $3110 

Creates  one  or  more  new  controls.  You  specify  the  parameters  governing  those  controls  in 
control  templates  that  are  passed  to  NewControi2  (see  "New  Control  Manager 
templates  and  records"  later  in  this  chapter).  If  NewControi2  creates  a  single  control,  it 
returns  the  handle  to  that  control  in  Result.  If  NewControi2  creates  two  or  more 
controls,  it  returns  0.  For  sample  code  showing  how  to  use  the  NewControi2  tool  call,  see 
"Control  Manager  code  example"  later  in  this  chapter. 

All  controls  created  by  NewControi2  have  new  style  control  records  and  are  extended 
controls. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ownerPtr 


referenceDesc 


reference 


Long— Space  for  result 

Long— Pointer  to  window  for  control(s) 
Word— Describes  contents  of  reference 
Long— Reference  of  a  type  defined  by  referenceDesc 
<— SP 


Stack  after  call 


Previous  contents 


Result 


Errors 
C 


None 


Long— Control  handle  (if  single  control  created)  or  0 
<— SP 


extern  pascal  Handle  NewControl2 (ownerPtr, 
referenceDesc,  reference) ; 

Pointer   ownerPtr; 
Word      referenceDesc; 
Long      reference; 
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referenceDesc         Defines  the  contents  and  type  of  item  referenced  by  reference. 
Possible  values  for  referenceDesc  are: 


singlePtr  0 

singleHandle  1 

singleResource  2 

ptrToPtr  3 

ptrToHandle  4 

ptrToResource  5 

handleToPtr  6 

handleToHandle  7 

handleToResource  8 
resourceToResource 


reference  is  a  pointer  to  a  single  item 

template 

reference  is  a  handle  for  a  single  item 

template 

reference  is  a  resource  ID  of  a  single 

item  template 

reference  is  a  pointer  to  a  list  of 

pointers  to  item  templates 

reference  is  a  pointer  to  a  list  of  handles 

for  item  templates 

reference  is  a  pointer  to  a  list  of 

resource  IDs  of  item  templates 

reference  is  a  handle  to  a  list  of  pointers 

to  item  templates 

reference  is  a  handle  to  a  list  of  handles 

for  item  templates 

reference  is  a  handle  to  a  list  of  resource 

IDs  of  item  templates 

9  reference  is  a  resource  ID  of  a 

list  of  resource  IDs  of  item  templates 


If  reference  defines  a  list,  that  list  is  a  contiguous  array  of  template 
references  (pointers,  handles,  or  resource  IDs),  terminated  with  a 
NULL  entry. 
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NotifyCtls     $2D10 

Calls  the  control  definition  procedures  for  extended  controls  in  a  specified  window, 
sending  a  specified  control  message  and  parameter.  You  determine  which  controls  are  to 
be  called  by  setting  up  the  mask  field.  This  routine  compares  the  value  of  mask  with  that 
of  the  ctiMoreFiags  field  of  the  control  record  for  each  control  in  the  window.  If  any 
of  the  bits  you  have  specified  in  mask  are  set  to  1  in  ctiMoreFiags,  the  control  is  sent 
the  message  you  have  specified  (mask  is  bitwise  ANDed  with  ctiMoreFiags;  a  nonzero 
result  yields  a  call  to  the  control). 

Set  the  param  parameter  to  0  if  the  control  definition  procedure  does  not  accept  an  input 
parameter  (see  "New  control  definition  procedure  messages"  earlier  in  this  chapter  for 
information  on  input  parameters  for  defProc  messages). 

Parameters 

Stack  before  call 


Previous  contents 


mask 


message 


param 


window 


Stack  after  call 


Word— Bit  mask  to  be  compared  with  ctiMoreFiags 
Word— Control  message  to  send  to  control  definition  procedures 
Long— Parameter  to  pass  to  control  definition  procedures 

Long— GrafPort  of  window  whose  control  list  is  to  be  searched 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  NotifyCtls (mask,  message,  param, 
window) ; 


Word      mask,  message; 
Long      param,  window; 
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SendEventToCtl     $2910 

Passes  a  specified  extended  task  record  (which  must  comply  with  the  new  format  defined 
in  Chapter  52,  "Window  Manager  Update,"  in  this  book)  to  the  appropriate  control  or 
controls.  This  call  returns  a  Boolean  indicating  whether  the  event  was  fielded  by  a  control, 
and  returns  the  handle  of  the  control  that  serviced  the  event  in  taskData2  of  the  task 
record  for  the  event. 

The  targetOnlyFlag  parameter  governs  the  way  the  Control  Manager  searches  for  a  control 
to  field  the  event.  If  targetOnlyFlag  is  set  to  TRUE,  SendEventToCtl  sends  the  event  to 
the  target  control.  If  there  is  no  target  control,  Result  is  FALSE  and  taskData2  is 
undefined. 

If  targetOnlyFlag  is  set  to  FALSE,  SendEventToCtl  conducts  a  two-part  search  for  a 
control  to  field  the  event.  First,  Control  Manager  looks  for  non-edit  field  controls  that 
want  keystrokes  (for  example,  buttons  with  keystroke  equivalents).  The  Control  Manager 
tries  to  send  the  event  to  each  such  control  (with  the  ctiHandieEvent  control 
message).  If  no  control  accepts  the  event,  the  Control  Manager  looks  for  an  edit  field 
control  (LineEdit  or  TextEdit)  that  can  become  the  target.  If  no  control  accepts  the 
event  and  there  is  no  target,  Result  is  FALSE  and  taskData2  is  undefined.  Otherwise, 
Result  is  TRUE  and  taskData2  contains  the  handle  of  the  accepting  control. 

This  call  is  valid  only  for  extended  controls. 


♦   Note:  If  a  control  can  be  made  the  target  (f  ctiCanBeTarget  is  set  to  1  in 
ctiMoreFiags  of  its  control  record),  then  the  Control  Manager  will  send  it  events 
regardless  of  the  setting  of  the  fctiwantsEvents  bit. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


targetOnlyFlag 


-     windowPtr    - 


-     eTaskRecPtr 


Word— Space  for  result  Boolean 

Word— (Boolean)  TRUE-send  to  target  only;  FALSE-all  controls 

Long— Pointer  to  window  to  search;  NIL  for  top  window 

Long— Pointer  to  extended  task  record  for  event 
<— SP 
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Stack  after  call 


Previous  contents 


Result 


Errors 


$1005 
$100C 


Word— (Boolean)  TRUE  if  event  accepted;  otherwise  FALSE 
<— SP 


noSuperCtlError 
noWind  Err 


No  extended  controls  in  window 
There  is  no  front  window 


extern  pascal  Boolean  SendEventToCtl (targetOnlyFlag, 
windowPtr,  eTaskRecPtr) ; 

Word      targetOnlyFlag; 
Pointer   windowPtr,  eTaskRecPtr; 
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SetCtllD     $2B10 

Sets  the  ctiiD  field  in  the  control  record  of  a  specified  control.  The  ctiiD  field  is  an 
application-defined  tag  for  a  control.  Your  application  can  use  this  field  in  many  ways. 
For  example,  since  the  value  of  ctiiD  is  knowable  at  compile  time,  you  can  construct 
efficient  routing  code  for  handling  control  messages  for  many  different  controls. 

Retrieve  the  ctiiD  field  for  a  control  with  the  GetctiiD  Control  Manager  call. 

If  the  specified  control  is  not  an  extended  control,  an  error  is  returned. 


Parameters 

Stack  before  call 

Previous  contents 

newID 

Long— New  ctiiD  value  for  the  control 

ctlHandle     - 

Long— Handle  to  control 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Em 

are                 $1004 
$1007 

noCtiError                   No  controls  in  window 
notSuperCtiError        Action  valid  only  for  extended 

controls 

extern  pascal  void  SetCtllD (newID,  ctlHandle); 


Long 
Handle 


newID; 
ctlHandle; 


28-38     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  I1GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


SetCtlMoreFlags     $2F10 

Sets  the  contents  of  the  ctiMoreFiags  field  of  the  control  record  for  a  specified 
control.  The  ctiMoreFiags  field  contains  flags  governing  target  status,  event 
processing,  and  other  aspects  of  the  control. 

Retrieve  the  ctiMoreFiags  field  for  a  control  with  the  GetctiMoreFiags  Control 
Manager  call. 

If  the  specified  control  is  not  an  extended  control,  an  error  is  returned. 

Parameters 

Stack  before  call 


Previous  contents 

newMoreFlags 

Word— New  ctiMoreFiags  value  for  the  control 

ctlHandle 

Long— Handle  to  control 

<— SP 

k  after  call 

Previous  contents 

<— SP 

ore                 $1004 
$1007 

noCtiError                   No  controls  in  window 
notsuperCtiError        Action  valid  only  for  extended 

controls 

extern  pascal  void  SetCtlMoreFlags (newMoreFlags, 
ctlHandle) ; 


Word 
Handle 


newMoreFlags; 
ctlHandle; 
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SetCtlParamPtr    $3410 

Sets  the  pointer  to  the  current  text  substitution  array  for  the  Control  Manager.  This  array 
contains  the  information  used  for  text  substitution  in  static  text  controls  (see  "Static 
text  controls"  elsewhere  in  this  chapter). 

Retrieve  the  contents  of  this  field  with  the  GetctiParamPtr  Control  Manager  tool  call. 


♦    Note:  This  pointer  is  global  to  the  Control  Manager;  it  is  not  associated  with  a 
specific  control.  As  a  result,  desk  accessories  should  be  very  careful  when  using  this 
feature  to  save  and  restore  the  previous  contents  of  the  field. 


Parameters 

Stack  before  call 

Previous  contents 

-    subArrayPtr    - 

Long— New  pointer  to  text  substitution  array 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C 

exte 

rn  pascal  void  SetCtlParamPtr (subArrayE 

Pointer        subArrayPointer; 
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Control  Manager  error  codes 


Value 


Name 


Definition 


$1001 

wmNotStartedUp 

$1002 

cmNot Initialized 

$1003 

noCtllnList 

$1004 

noCtlError 

$1005 

noSuperCtlError 

$1006 

noCtlTargetError 

$1007 

notSuperCtlError 

$1008 

canNotBeTargetError 

$1009 

noSuchlDError 

$100A 

tooFewParmsError 

$100B 

noCtlToBeTargetError 

$100C 

noWind  Err 

Window  Manager  not  initialized 

Control  Manager  not  initialized 

Control  not  in  window  list 

No  controls  in  window 

No  extended  controls  in  window 

No  target  extended  control. 

Action  valid  only  for  extended  controls 

Specified  control  cannot  be  made 

target 

The  specified  ID  cannot  be  found 

Too  few  parameters  specified 

No  control  could  be  made  target 

There  is  no  front  window 
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New  Control  Manager  templates  and  records 

This  section  describes  the  format  and  content  of  all  Control  Manager  control  templates 
and  records.  In  addition,  "Control  Manager  code  example"  shows  how  to  use  control 
templates  with  the  NewControi2  tool  call. 


NewControl2  input  templates 

Each  type  of  control  has  its  own  control  template,  corresponding  to  the  control  record 
definition  for  the  control  type.  The  item  template  is  an  extensible  mechanism  for  defining 
new  controls.  Rather  than  placing  all  the  control  parameters  on  the  stack  at  run  time,  the 
template  holds  these  parameters  in  a  standard  format  that  can  be  defined  at  compile 
time.  Furthermore,  the  templates  can  be  created  as  a  resource,  simplifying  program 
development  and  maintenance,  reducing  code  size,  and  reducing  fixed  memory  usage. 
Your  program  can  pass  more  than  one  input  template  to  NewControi2  at  a  time. 

All  control  templates  have  the  same  seven-field  header.  Some  templates  have  additional 
fields  that  further  define  the  control.  In  order  to  provide  extensible  support  for  variable 
length  templates,  one  of  the  header  fields  is  a  parameter  count.  The  value  of  the 
parameter  count  field  tells  the  Control  Manager  how  many  parameters  to  use,  which  allows 
for  optional  template  fields. 

The  following  sections  define  the  item  templates  for  each  control  type.  Field  names 
marked  with  an  asterisk  (*)  represent  optional  fields. 
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Control  template  standard  header 

Each  control  template  contains  the  standard  header,  which  consists  of  seven  fields. 
Following  that  header,  some  templates  have  additional  fields,  which  further  define  the 
control  to  be  created.  The  format  and  content  of  the  standard  template  header  is  shown 
in  Figure  28-1. 

Custom  control  definition  procedures  establish  their  own  item  template  layout.  The  only 
restriction  placed  on  these  templates  is  that  the  standard  header  be  present  and  well 
formed.  Custom  data  for  the  control  procedure  may  follow  the  standard  header. 


Figure  28-1      Control  template  standard  header 


$00 

pCount 

- 

Word 

$02 

ID 

- 

Long 

$06 

rect 

Rectar 

$0E 

procRef 

~" 

Long 

$12 

flag 

Word 

$14 

moreFlags 

Word 

$16 

re f Con 

Long 

pCount 


Count  of  parameters  in  the  item  template,  not  including  the  pCount 
field.  Minimum  value  is  6,  maximum  value  varies  depending  upon  the 
type  of  control  template. 
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ID 


rect 


procRef 


Sets  the  ctiiD  field  of  the  control  record  for  the  new  control.  The 
ctim  field  may  be  used  by  the  application  to  provide  a 
straightforward  mechanism  for  keeping  track  of  controls.  The  control 
ID  is  a  value  assigned  by  your  application,  which  the  control  "carries 
around"  for  your  convenience.  Your  application  can  use  the  ID,  which 
has  a  known  value,  to  identify  a  particular  control. 

Sets  the  ctiRect  field  of  the  control  record  for  the  new  control. 
Defines  the  boundary  rectangle  for  the  control. 

Sets  the  ctiProc  field  of  the  control  record  for  the  new  control.  This 
field  contains  a  reference  to  the  control  definition  procedure  for  the 
control.  The  value  of  this  field  is  either  a  pointer  to  a  control 
definition  procedure,  or  the  ID  of  a  standard  routine.  The  standard 
values  are: 


simpleButtonControl 

$80000000 

Simple  button 

checkControl 

$82000000 

Check  box 

iconButtonControl 

$07FF0001 

Icon  button 

editLineControl 

$83000000 

LineEdit 

listControl 

$89000000 

List 

pictureControl 

$8D000000 

Picture 

popUpControl 

$87000000 

Pop-up 

radioControl 

$84000000 

Radio  control 

scrollBarControl 

$86000000 

Scroll  bar 

growControl 

$88000000 

Size  box 

statTextControl 

$81000000 

Static  Text 

editTextControl 

$85000000 

TextEdit 
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flag  A  word  used  to  set  both  ctiHiiite  and  ctiFlag  in  the  control 

record  for  the  new  control.  Since  this  is  a  word,  the  bytes  for 
ctiHiiite  and  ctiFlag  are  reversed.  The  high-order  byte  of  flag 
contains  ctiHiiite,  while  the  low-order  byte  contains  ctiFlag. 
The  bits  in  flag  are  mapped  as  follows: 

Highlight  bits  8-15  Indicates  highlighting  style: 

0  Control  active,  no  highlighted 

parts 
1-254    Part  code  of  highlighted  part 
255       Control  inactive 

Invisible  bit  7         Governs  visibility  of  control: 

0  -  Control  visible 

1  -  Control  invisible 

Variable  bits  0-6    Values  and  meaning  depends  upon 

control  type 
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moreFiags  Used  to  set  the  ctiMoreFiags  field  of  the  control  record  for  the 

new  control. 

The  high-order  byte  is  used  by  the  Control  Manager  to  store  its  own 
control  information.  The  low-order  byte  is  used  by  the  control 
definition  procedure  to  define  reference  types. 

The  defined  Control  Manager  flags  are: 


fCtlTarget  $8000 

fCtlCanBeTarget     $4000 
fCtlWantEvents      $2000 


fCtlProcRefNotPtr    $1000 


fCtlTellAboutSize   $0800 


fCtllsMultiPart     $0400 


If  set  to  1,  this  control  is  currently  the  target  of 
any  typing  or  editing  commands. 
If  set  to  1  then  this  control  can  be  made  the 
target  control. 

If  set  to  1  then  this  control  can  be  called  when 
events  are  passed  via  the  sendEventTocti 
Control  Manager  call.  Note  that,  if  the 
fCtlCanBeTarget  flag  is  set  to  1,  this  control 
will  receive  events  sent  to  it  regardless  of 
setting  of  this  flag. 

If  set  to  1,  then  Control  Manager  expects 
ctiProc  to  contain  the  ID  of  a  standard 
control  procedure.  If  set  to  0,  then  c tip  roc 
contains  a  pointer  to  the  custom  control 
procedure. 

If  set  to  1,  then  this  control  needs  to  be 
notified  when  the  size  of  the  owning  window 
has  changed.  This  flag  allows  custom  control 
procedures  to  resize  their  associated  control 
images  in  response  to  changes  in  window  size. 
If  set  to  1,  then  this  is  a  multipart  control.  This 
flag  allows  control  definition  procedures  to 
manage  multi-part  controls  (necessary  since  the 
Control  Manager  does  not  know  about  all  the 
parts  of  a  multi-part  control). 
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The  low-order  byte  uses  the  following  convention  to  describe 
references  to  color  tables  and  titles  (note,  though,  that  some  control 
templates  do  not  follow  this  convention): 


titlelsPtr 

$00 

Title  reference  is  by  pointer 

titlelsHandle 

$01 

Title  reference  is  by  handle 

titlelsResource 

$02 

Title  reference  is  by  resource  ID 

colorTablelsPtr  $00 
colorTablelsHandle  $04 
colorTablelsResource  $08 


Color  table  reference  is  by  pointer 
Color  table  reference  is  by  handle 
Color  table  reference  is  by  resource  ID 


refCon 


Used  to  set  the  ctiRef  Con  field  of  the  control  record  for  the  new 
control.  Reserved  for  application  use. 
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Keystroke  equivalent  information 

Many  of  these  control  templates  allow  you  to  specify  keystroke  equivalent  information 
for  the  associated  controls.  Figure  28-2  shows  the  standard  format  for  that  keystroke 
information. 


Figure  28-2      Keystroke  equivalent  record  layout 


$00 

keyl 

Byte 

$01 

key2 

Byte 

$02 

—      keyModifiers      — 

Word 

$04 

—       keyCareBits       — 

Word 

keyl 
key2 


keyModifiers 


keyCareBits 


This  is  the  ASCII  code  for  the  upper  or  lower  case  of  the  key 
equivalent. 

This  is  the  ASCII  code  for  the  lower  or  upper  case  of  the  key 
equivalent  Taken  with  keyl,  this  field  completely  defines  the  values 
against  which  key  equivalents  will  be  tested.  If  only  a  single  key  code 
is  valid,  then  set  keyl  and  key2  to  the  same  value. 

These  are  the  modifiers  that  must  be  set  to  1  in  order  for  the 
equivalence  test  to  pass.  The  format  of  this  flag  word  corresponds  to 
that  defined  for  the  event  record  in  Chapter  7,  "Event  Manager,"  in 
Volume  1  of  the  Toolbox  Reference.  Note  that  only  the  modifiers  in  the 
high-order  byte  are  used  here. 

These  are  the  modifiers  that  must  match  for  the  equivalence  test  to 
pass.  The  format  for  this  word  corresponds  to  that  for 
keyModifiers.  This  word  allows  you  to  discriminate  between 
double-modified  keystrokes.  For  example,  if  you  want  Control-7  to 
be  an  equivalent,  but  not  Option-Control-7,  you  would  set  the 
controlKey  bit  in  keyModifiers  and  both  the  optionKey  and  the 
controlKey  bits  in  keyCareBits  to  1.  If  you  want  Return  and  Enter 
to  be  treated  the  same,  the  keyPad  bit  should  be  set  to  0. 
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Simple  button  control  template 

Figure  28-3  shows  the  template  that  defines  a  simple  button  control. 

■    Figure  28-3      Item  template  for  simple  button  controls 

Word— Parameter  count  for  template:  7, 8,  or  9 
Long— Application-assigned  control  ID 

Rectangle — Boundary  rectangle  for  control 

Long— simpleButtonControl  =$80000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 
Long— Reference  to  title  for  button 
Long-Reference  to  color  table  for  control  (optional) 


$00 

- 

pCount 

- 

$02 

_ 

— 

ID 

- 

— 

$06 

rect 

$0E 

_ 

procRef 

: 

$12 

flag 

- 

$14 

moreFlags 

- 

$16 

_ 

refCon 

- 

$1A 

_ 

titleRef 

- 

— 

HE 

_ 

*colorTableRef 

- 

— 

$22 

* keyEqu i va 1 ent 

1 
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Defined  bits  for  flag  are 

I  Reserved  bits  8-15 

ctllnvis  bit  7 

Reserved  bits  2-6 

Button  type  bits  0-1 


Defined  bits  formoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  4-10 

Color  table  reference 

bits  2-3 

Title  reference 


bits  0-1 


Must  be  set  to  0 
1  "invisible,  0=visible 
Must  be  set  to  0 
Describes  button  type: 

0  -  single-outlined  round-cornered  button 

1  -  bold-outlined  round-cornered  button 

2  "  single-outlined  square-cornered  button 

3  ■  single-outlined  square-cornered  drop- 
shadowed  button 


Must  be  set  to  0 

Must  be  set  to  0 

Set  to  1  if  button  has  keystroke  equivalent 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef . 

See  Chapter  4,  "Control  Manager,"  in  Volume  1 

of  the  Toolbox  Reference  for  the  definition  of 

the  simple  button  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11 -invalid  value 

Defines  type  of  title  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  title  reference  is  resource  ID 
11 -invalid  value 


keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  28-2. 
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Check  box  control  template 

Figure  28-4  shows  the  template  that  defines  a  check  box  control. 

■    Figure  284      Control  template  for  check  box  controls 


$00 
$02 
$06 

$0E 

$12 
$14 
$16 


pCount 


ID 


Word— Parameter  count  for  template:  8, 9,  or  10 


Long— Application-assigned  control  ID 
:  Rectangle— Boundary  rectangle  for  control 


—  moreFlags 


$1A_ 


$1E 
$20 

$24 


procRef 


flag  -|  Word— Highlight  and  control  flags  for  control 

Word— Additional  control  flags 


ref  con  -   Long— Application-defined  value 


-        inltlalValue 


Long— checkBoxControl  =$82000000 


titieRef         -   Long— Reference  to  title  for  box 


Word— Initial  box  setting:  0  for  clear,  1  for  checked 


-     *coiorTabieRef    -   Long— Reference  to  color  table  for  control  (optional) 


•keyEquivaient      '.  Block,  6  bytes— Keystroke  equivalent  data  (optional) 


Defined  bits  for  flag  are 


Reserved 

bits  8-15 

Must  be  set  to  0 

ctllnvis 

bit  7 

1 -invisible,  Ovisible 

Reserved 

bits  0-6 

Must  be  set  to  0 
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fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  4-10 

Color  table  reference 

bits  2-3 

Defined  bits  formoreFiags  are 

Must  be  set  to  0 

Must  be  set  to  0 

Set  to  1  if  check  box  has  keystroke  equivalent 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef 

(see  Chapter  4,  "Control  Manager,"  in  Volume  1 

of  the  Toolbox  Reference  for  the  definition  of 

the  check  box  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 
10  -  color  table  reference  is  resource  ID 
11 -invalid  value 
Defines  type  of  title  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  title  reference  is  resource  ID 
11 -invalid  value 

keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  28-2. 


Title  reference 


bits  0-1 
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Icon  button  control  template 

Figure  28-5  shows  the  template  that  defines  an  icon  button  control.  For  more  information 
about  icon  button  controls,  see  "Icon  button  control"  in  this  chapter. 


Figure  28-5      Control  template  for  icon  button  controls 


$00 
$02 
$06 

$0E 

$12 
$14 
$16 

$1A 

$1E 

$22 

$26 
$28 


pcount  -   Word— Parameter  count  for  template:  7, 8, 9, 1 0,  or  1 1 


Long— Application-assigned  control  ID 


|  Rectangle— Boundary  rectangle  for  control 


procRef 


flag 


Word— Highlight  and  control  flags  for  control 
moreFiags        -|  Word— Additional  control  flags 


re  f  con  -   Long— Application-defined  value 


•displayMode 


Long— iconButtonControl  =$07FF0001 


i  conRe  f  -   Long— Reference  to  icon  for  control 


titieRef        -   Long— Reference  to  title  for  control  (optional) 


-     *coiorTabieRef    -   Long— Reference  to  color  table  for  control  (optional) 


Word— Bit  flag  controlling  icon  appearance  (optional) 


•keyEquivaient       '■  Block,  6  bytes — Key  equivalent  information  (optional) 
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Defined  bits  for  flag  are 


ctlHilite 

bits  8-15 

ctllnvis 

bit  7 

Reserved 

bits  3-6 

showBorder 

bit  2 

buttonType 

bits  0-1 

Defined  bits  formoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  6-10 

Icon  reference 

bits  4-5 

Color  table  reference 


bits  2-3 


Title  reference 


bits  0-1 


Sets  the  ctlHilite  field  of  the  control  record 

l=invisible,  0-visible 

Must  be  set  to  0 

1-No  border,  0=Show  border 

Defines  button  type: 

00  -  single-outlined  round-cornered  button 

01  -  bold-outlined  round-cornered  button 

10  -  single-outlined  square-cornered  button 

11  -  single-outlined  square-cornered  and  drop- 
shadowed  button 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 
Defines  type  of  icon  reference  in  iconRef : 

00  -  icon  reference  is  pointer 

01  -  icon  reference  is  handle 

10  -  icon  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  reference  in  coiorTabieRef ; 
the  color  table  for  an  icon  button  is  the  same  as 
that  for  a  simple  button  (see 
Chapter  4,  "Control  Manager,"  in  Volume  1  of 
the  Toolbox  Reference  for  the  definition  of  the 
simple  button  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  title  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  tide  reference  is  resource  ID 
11 -invalid  value 
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titleRef 


displayMode 


Reference  to  the  title  string,  which  must  be  a  Pascal  string.  If  you  are 
not  using  a  title  but  are  specifying  other  optional  fields,  set 
moreFiags  bits  0  and  1  to  0,  and  set  this  field  to  zero. 

Passed  directly  totheDrawicon  routine,  and  defines  the  display 
mode  for  the  icon.  The  field  is  defined  as  follows  (for  more 
information  on  icons,  see  Chapter  17,  "QuickDraw  II  Auxiliary,"  in 
Volume  2  of  the  Toolbox  Reference): 


Background 

Color 

bits  12-15 

Defines  the  background  color  to  apply  to  black 
part  of  black-and-white  icons. 

Foreground  Color 

bits  8-11 

Defines  the  foreground  color  to  apply  to  white 

part  of  black-and-white  icons. 

Reserved 

bits  3-7 

Must  be  set  to  0 

offLine 

bit  2 

1»AND  light-gray  pattern  to  image  being 

copied 

O-Don't  AND  the  image 

openlcon 

bit  1 

1-Copy  light-gray  pattern  instead  of  image 
0-Don't  copy  light-gray  pattern 

selectedl 

con 

bitO 

1 -Invert  image  before  copying 
0=Don't  invert  image 

Color  values  (both  foreground  and  background)  are  indexes  into  the 
current  color  table.  See  Chapter  16,  "QuickDraw  II,"  in  Volume  2  of  the 
Toolbox  Reference  for  details  about  the  format  and  content  of  these 
color  tables. 

keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  28-2. 
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LineEdit  control  template 

Figure  28-6  shows  the  template  that  defines  a  LineEdit  control.  For  more  information 
about  LineEdit  controls,  see  "LineEdit  control"  in  this  chapter. 


Figure  28-6      Control  template  for  LineEdit  controls 


$00 
$02 

$06 
$0E 

$12 
$14 
$16 

$1A 
SIC 


—  raoreFlags 


ID 


rect 


flag 


refCon 


pcount  -   Word— -Parameter  count  for  template  8 

Long-rApplication-assigned  control  ID 


]  Rectangle— Boundary  rectangle  for  control 


procRef  -    Long—  editLineControl  =$83000000 


Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 


Long— Application-defined  value 
maxsize  -j  Word— Maximum  length  of  input  line  (in  bytes) 

defauitRef       -j  Long— Reference  to  default  text 


Defined  bits  for  flag  are 


Reserved 

bits  8-15 

Must  be  set  to  0 

ctllnvis 

bit  7 

1 -invisible,  0-visible 

Reserved 

bits  0-6 

Must  be  set  to  0 
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Defined  bits  formoreFiags  are 


fCtlTarget 

bit  15 

Must  be  set  to  0 

fCtlCanBeTarget 

bit  14 

Must  be  set  to  1 

fCtlWantsEvents 

bit  13 

Must  be  set  to  1 

fCtlProcNotPtr 

bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11 

Must  be  set  to  0 

Reserved 

bits  2-10 

Must  be  set  to  0 

Text  reference 

bits  0-1 

Defines  type  of  text  reference  in  default  Re  f 

00  -  text  reference  is  pointer 

01  -  text  reference  is  handle 

10  -  text  reference  is  resource  ID 
11 -invalid  value 

maxsize  Specifies  the  maximum  number  of  characters  allowed  in  the  LineEdit 

field.  Valid  values  lie  in  the  range  from  1  to  255. 

The  high-order  bit  indicates  whether  the  LineEdit  field  is  a  password 
field.  Password  fields  protect  user  input  by  echoing  asterisks,  rather 
than  the  actual  user  input.  If  this  bit  is  set  to  1,  then  the  LineEdit  field 
is  a  password  field. 

Note  that  LineEdit  controls  do  not  support  color  tables. 
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List  control  template 

Figure  28-7  shows  the  template  that  defines  a  list  control.  For  more  information  about  list 
controls,  see  "List  control"  in  this  chapter. 


Figure  28-7      Control  template  for  list  controls 


$06 


—  pcount  —   Word— Parameter  count  for  template:  14  or  15 


—   Long— Application-assigned  control  ID 


Rectangle— Boundary  rectangle  for  control 

($0E)  Long— listControl  =$89000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 

Word— Number  of  members  in  list 
Word— Number  of  members  visible  in  window 
Word— Type  of  list  entries,  selection  options,  etc. 
Word— First  visible  list  member 

Long— Pointer  to  member  drawing  routine 

Word— Height  of  each  list  item  (in  pixels) 
Word— Size  of  list  entry  (in  bytes) 

Long— Reference  to  list  of  member  records 
Long— Reference  to  color  table  for  control  (optional) 


rect 

$0E 

— 

procRef 

— 

$12 

flag 

— 

$14 

moreFlags 

— 

$16 

refcon 

_ 

$1A 

—            listSize            — 

$1C 

UstView 

— 

$1E 

11 st Type 

— 

$20 

liststart 

— 

$22 

llstDraw 

_ 

$26 

listMemHelght 

— 

$28 

UstMemSlze 

— 

$2A 

listRef 

— 

$2E 

•colorTableRef 

"""" 
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Defined  bits  for  flag  are 

Reserved  bits  8-15 

ctllnvis  bit  7 

Reserved  bits  0-6 

Defined  bits  for  moreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

fCtllsMultiPart 

Reserved 

Color  table  reference 


bit  15 
bit  14 
bit  13 
bit  12 
bit  11 
bit  10 
bits  4-9 
bits  2-3 


List  reference 


bits  0-1 


Must  be  set  to  0 
1 -invisible,  0= visible 
Must  be  set  to  0 


Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef 

(the  color  table  for  a  List  control  is  described  in 

Chapter  11,  "List  Manager,"  in  Volume  1  of  the 

Toolbox  Reference) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 
11 -invalid  value 

Defines  type  of  reference  in  listRef  (the 
format  for  a  list  member  record  is  described  in 
Chapter  11,  "List  Manager,"  in  Volume  1  of  the 
Toolbox  Reference) 

00  -  list  reference  is  pointer 

01  -  list  reference  is  handle 

10  -  list  reference  is  resource  ID 
11 -invalid  value 
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listType 

Reserved 

fListScrollBar 


Valid  values  for  listType  are  as  follows: 


bits3— 15       Must  be  set  to  0. 

bit  2  Allows  you  to  control  where  the  scroll  bar  for  the 

list  is  drawn: 

1  -  Scroll  bar  drawn  on  inside  of  boundary 
rectangle.  The  List  Manager  calculates  space 
needed,  adjusts  dimensions  of  boundary 
rectangle,  and  resets  this  flag. 

0  -  Scroll  bar  drawn  on  outside  of  boundary 
rectangle. 

bit  1  Controls  type  of  selection  options  available  to 

the  user: 

1  -  Only  single  selection  allowed 

0  -  Arbitrary  and  range  selection  allowed 
bit  0             Defines  the  type  of  strings  used  to  define  list 

items: 

1  -  C-strings  ($00-terminated) 
0  -  Pascal  strings 

For  details  on  the  remaining  custom  fields  in  this  template,  see  the  discussion  of  "List 
Controls  and  List  Records"  in  Chapter  11,  "List  Manager,"  of  Volume  1  of  the  Toolbox 
Reference. 


fListSelect 


fListString 
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Picture  control  template 

Figure  28-8  shows  the  template  that  defines  a  picture  control.  For  more  information  about 
picture  controls,  see  "Picture  control"  in  this  chapter. 


Figure  28-8      Control  template  for  picture  controls 


$00 

pCount 

- 

$02 

— 

ID 

- 

— 

$06 

rect 

$0E 

— 

procRef 

- 

$12 

flag 

- 

$14 

moreFlags 

- 

$16 

— 

re f Con 

- 

- 

$1A 

_ 

— 

- 

plctureRef 

- 

- 

_ 

Word— Parameter  count  for  template:  7 
Long— Application-assigned  control  ID 

Rectangle— Boundary  rectangle  for  control 

Long— pictureControl  =$8D000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 
-|  Long— Reference  to  picture  for  control 


Defined  bits  for  flag  are 


ctlHilite 

bits  8-15 

Specifies  whether  the  control  wants  to  receive 
mouse  selection  events;  the  values  for 
ctlHilite  are  as  follows: 
0          Control  is  active 
255       Control  is  inactive 

ctllnvis 

bit  7 

1 -invisible,  Ovisible 

Reserved 

bits  0-6 

Must  be  set  to  0 
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Defined  bits  for  moreFiags  are 


fCtlTarget 

bit  15 

Must  be  set  to  0 

fCtlCanBeTarget 

bit  14 

Must  be  set  to  0 

fCtlWantsEvents 

bit  13 

Must  be  set  to  0 

fCtlProcNotPtr 

bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11 

Must  be  set  to  0 

Reserved 

bits  2-10 

Must  be  set  to  0 

Picture  reference 

bits  0-1 

Define  type  of  picture  reference  in 
pictureRef: 

00  -  invalid  value 

01  -  reference  is  handle 

10  -  reference  is  resource  ID 
11 -invalid  value 
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Pop-up  control  template 

Figure  28-9  shows  the  template  that  defines  a  pop-up  control.  For  more  information  about 
pop-up  controls,  see  "Pop-up  control"  in  this  chapter. 


Figure  28-9      Control  template  for  pop-up  controls 

Word— Parameter  count  for  template:  9  or  10 
-   Long— Application-assigned  control  ID 

\  Rectangle— Boundary  rectangle  for  control 

Long— popUpCont  ro  1 =$87000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 

Word— Width  in  pixels  of  title  string  area 

Long— Reference  to  menu  definition 

Word— Item  ID  of  initial  item 

Long— Reference  to  color  table  for  control  (optional) 


$00 

pCount 

- 

$02 

— 

ID 

- 

— 

$06 

rect 

$0E 

— 

procRef 

- 

~ 

$12 

flag 

- 

$14 

moreFlags 

- 

$16 

— 

refCon 

- 

- 

$1A 

titleWidth 

- 

$1C 

— 

menuRef 

- 

— 

$20 

initialValue 

- 

$22 

_ 

•colorTableRef 

- 

— 
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Defined  bits  for  flag  are 
ctlHilite  bits  8-15 


ctllnvis 
fType2PopUp 


bit  7 
bit  6 


fDontHiliteTitle    bit  5 


fDontDrawTitle 


bit  4 


fDontDrawResult     bit  3 


flnWindowOnly 


bit  2 


Specifies  whether  the  control  wants  to  receive 
mouse  selection  events;  the  values  for 
ctlHilite  are  as  follows: 

0  Control  is  active 
255        Control  is  inactive 
1 -invisible,  0-visible 

Tells  the  Control  Manager  whether  to  create  a 
pop-up  menu  with  white  space  for  scrolling  (see 
Chapter  37,  "Menu  Manager  Update,"  for  details 
on  Type  2  pop-up  menus): 

1  -  Draw  pop-up  with  white  space  (Type  2) 

0  -  Draw  normal  pop-up 

Controls  highlighting  of  the  control  title: 

1  -  Do  not  highlight  title  when  control  is  popped 
up 

0  -  Highlight  title 

Allows  you  to  prevent  the  title  from  being  drawn 
(note  that  you  must  supply  a  title  in  the  menu 
definition,  whether  or  not  it  will  be  displayed); 
if  titiewidth  is  defined  and  this  bit  is  set  to 
1,  then  the  entire  menu  is  offset  to  the  right  by 
titiewidth  pixels: 

1  -  Do  not  draw  the  tide 

0  -  Draw  the  title 

Allows  you  to  control  whether  the  selection  is 
drawn  in  the  pop-up  rectangle: 

1  -  Do  not  draw  the  result  in  the  result  area  after 
a  selection 

0- Draw  the  result 

Controls  the  extent  to  which  the  pop-up  menu 

can  grow;  this  is  particularly  relevant  to  Type  2 

pop-ups  (see 

Chapter  37,  "Menu  Manager  Update,"  for  details 

on  Type  2  pop-up  menus): 

1  -  Keep  the  pop-up  in  the  current  window 

0  -  Allow  the  pop-up  to  grow  to  screen  size 
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fRightJustifyTitle  bit  1 


fRight JustifyResult  bit  0 


Defined  bits  formoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  5-10 

Color  table  reference 

bits  3-4 

fMenuDeflsText 


bit  2 


Controls  title  justification: 

1  -  Right  justify  the  title;  note  that  if  the  title  is 

right  justified,  then  the  control  rectangle  is 

adjusted  to  eliminate  unneeded  pixels  (see 

Figure  28-12),  the  value  for  titiewidth  is  also 

adjusted 

0  -  Left  justify  the  tide 
Controls  result  justification: 

1  -  Right  justify  the  selection 

0  -  Left  justify  the  selection  titiewidth 
pixels  from  the  left  of  the  pop-up  rectangle. 


Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  1  if  the  pop-up  has  any 

keystroke  equivalents  defined 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef 

(the  color  table  for  a  menu  is  described  in 

Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the 

Toolbox  Reference) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  data  referred  to  by  menuRef : 

1  -  menuRef  is  a  pointer  to  a  text  stream  in 

NewMenu  format  (see 

Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the 

Toolbox  Reference  for  details) 

0  -  menuRef  is  a  reference  to  a  Menu  Template 

(again,  see  Chapter  13,  "Menu  Manager,"  in 

Volume  1  of  the  Toolbox  Reference  for  details  on 

format  and  content  of  a  Menu  Template) 
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Menu  reference 


rect 


initialValue 


titleWidth 


menuRef 


bits  0-1         Defines  type  of  menu  reference  in  menuRef  (if 
fMenuDef  isText  is  set  to  1,  then  these  bits 
are  ignored): 

00  -  menu  reference  is  pointer 

01  -  menu  reference  is  handle 

10  -  menu  reference  is  resource  ID 
11 -invalid  value 

Defines  the  boundary  rectangle  for  the  pop-up  and  its  title,  before  the 
menu  has  been  "popped"  by  the  user.  The  Menu  Manager  will  calculate 
the  lower,  right  coordinates  of  the  rectangle  for  you,  if  you  specify 
those  coordinates  as  (0,0). 

The  initial  value  to  be  displayed  for  the  menu.  The  initial  value  is  the 
default  value  for  the  menu,  and  is  displayed  in  the  pop-up  rectangle  of 
"unpopped"  menus.  You  specify  an  item  by  its  ID,  that  is,  its  relative 
position  within  the  array  of  items  for  the  menu  (see 
Chapter  37,  "Menu  Manager  Update,"  for  information  on  the  layout 
and  content  of  the  pop-up  menu  template).  If  you  pass  an  invalid 
item  ID  then  no  item  is  displayed  in  the  pop-up  rectangle. 

Provides  you  with  additional  control  over  placement  of  the  menu  on 
the  screen.  The  titleWidth  field  defines  an  offset  from  the  left 
edge  of  the  control  (boundary)  rectangle  to  the  left  edge  of  the  pop- 
up rectangle  (see  Figure  28-11).  If  you  are  creating  a  series  of  pop-up 
menus  and  you  want  them  to  be  vertically  aligned,  you  can  do  this  by 
giving  all  menus  the  same  xl  coordinate  and  titleWidth  value.  You 
may  use  titleWidth  for  this  even  if  you  are  not  going  to  display  the 
title  (f  DontDrawTitie  flag  is  set  to  1  in  flag).  If  you  set 
titiewidth  to  0,  then  the  Menu  Manager  determines  its  value  based 
upon  the  length  of  the  menu  tide,  and  the  pop-up  rectangle 
immediately  follows  the  title  string.  If  the  actual  width  of  your  title 
exceeds  the  value  of  titleWidth,  results  are  unpredictable. 

Reference  to  menu  definition  (see  Chapter  13,  "Menu  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  and 

Chapter  37,  "Menu  Manager  Update,"  in  this  book  for  details  on  menu 
templates).  The  type  of  reference  contained  in  menuRef  is  defined 
by  the  menu  reference  bits  in  moreFiags. 
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m    Figure  28-10     "Unpopped"  pop-up  menu 
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Figure  28-11     "Popped"  pop-up  menu,  left-justified  title 
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Figure  28-12     "Popped"  pop-up  menu,  right-justified  title 
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Radio  button  control  template 

Figure  28-13  shows  the  template  that  defines  a  radio  button  control: 

■    Figure  28-13    Control  template  for  radio  button  controls 


$00 


$02  _ 


$06 


pcount  -  Word— Parameter  count  for  template:  8, 9,  or  10 


ID 


-   Long— Application-assigned  control  ID 
'•  Rectangle — Boundary  rectangle  for  control 


$0E  _ 


$12 
$14 
$16 

$1A 

$1E 
$20 

$24 


—  moreFlags 


procRef 


flag 


re  f  con  -   Long— Application-defined  value 


—      *colorTableRef      — 


Long— radioButtonControl  =$84000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 


titieRef         -   Long— Reference  to  title  for  button 


initiaivaiue      -   Word— Initial  setting:  0  for  clear,  1  for  set 


Long— Reference  to  color  table  for  control  (optional) 


:       *keyEquivaient       '■_  Block,  6  bytes— Keystroke  equivalent  data  (optional) 
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Defined  bits  for  flag  are 


Reserved 

bits  8-15 

ctllnvis 

bit  7 

Family  number 

bits  0-6 

Must  be  set  to  0 

1  "invisible,  0=visible 

Family  numbers  define  associated  groups  of 

radio  buttons;  radio  buttons  in  the  same  family 

are  logically  linked,  that  is,  setting  one  radio 

button  in  a  family  clears  all  other  buttons  in  the 

same  family 

Defined  bits  formoreFiags  are  as  follows: 

Must  be  set  to  0 

Must  be  set  to  0 

Set  to  1  if  button  has  keystroke  equivalent 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef 

(see  Chapter  4,  "Control  Manager,"  in  Volume  1 

of  the  Toolbox  Reference  for  the  definition  of 

the  radio  button  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 
10  -  color  table  reference  is  resource  ID 
11 -invalid  value 
Defines  type  of  title  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  DO 
11 -invalid  value 

keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  28-2. 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

f Ct lWant sEvent s 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  4-10 

Color  table  reference 

bits  2-3 

Title  reference 


bits  0-1 
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Scroll  bar  control  template 

Figure  28-14  shows  the  template  that  defines  a  scroll  bar  control: 

■    Figure  28-14    Control  template  for  scroll  bar  controls 


$00 

pCount 

- 

$02 

— 

ID 

- 

$06 

rect 

$0E 

— 

procRef 

- 

~ 

$12 

flag 

- 

$14 

moreFlags 

- 

$16 

— 

re f Con 

- 

— 

- 

$1A 

maxSize 

- 

$1C 

viewSize 

- 

$1E 

- 

inltialValue 

- 

$20 

_ 

— 

•colorTableRef 

- 

— 

Word— Parameter  count  for  template:  9  or  10 
Long— Application-assigned  control  ID 

:  Rectangle— Boundary  rectangle  for  control 

Long— scrollControl  =$86000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 

Word— Initial  size  of  displayed  item 
Word— Amount  of  item  initially  visible 
Word— Initial  setting 

-]  Long— Reference  to  color  table  for  control  (optional) 
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Defined  bits  for  flag  are 

Must  be  set  to  0 
1 -invisible,  0=visible 
Must  be  set  to  0 

1-horizontal  scroll  bar,  0=vertical  scroll  bar 
l=bar  has  right  arrow,  0=bar  has  no  right  arrow 
1-bar  has  left  arrow,  0=bar  has  no  left  arrow 
1-bar  has  down  arrow,  0-bar  has  no  down  arrow 
l«bar  has  up  arrow,  0-bar  has  no  up  arrow 

Note  that  extraneous  flag  bits  are  ignored,  based  upon  state  of  horscroii  flag.  For 
example,  for  vertical  scroll  bars,  rightFiag  and  lef  tFiag  are  ignored. 


Reserved 

bits  8-15 

ctllnvis 

bit  7 

Reserved 

bits  5-6 

horScroll 

bit  4 

rightFiag 

bit  3 

leftFlag 

bit  2 

downFlag 

bit  1 

upFlag 

bitO 

Defined  bits  for  moreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  4-10 

Color  table  reference 

bits  2-3 

Reserved 


bits  0-1 


Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  colorTableRefiszz 

Chapter  4,  "Control  Manager,"  in  Volume  1  of 

the  Toolbox  Reference  and  "Clarifications"  earlier 

in  this  chapter  for  the  definition  of  the  scroll 

bar  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
Must  be  set  to  0 
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Size  box  control  template 

Figure  28-15  shows  the  template  that  defines  a  size  box  control: 

■    Figure  28-15    Control  template  for  size  box  controls 

Word— Parameter  count  for  template:  6  or  7 
Long— Application-assigned  control  ID 

I  Rectangle— Boundary  rectangle  for  control 

Long—  gr  owCont  ro  1  =$88000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 

Long— Reference  to  color  table  for  control  (optional) 


$00 

- 

pCount 

- 

$02 

— 

_ 

- 

ID 

- 

— 

— 

$06 

rect 

$0E 

_ 

procRef 

- 

— 

$12 

flag 

- 

$14 

moreFlags 

- 

$16 

_ 

re f Con 

- 

— 

$20 

_ 

•colorTableRef 

- 

— 

Defined  bits  for  flag  are 


Reserved 

bits  8-15 

Must  be  set  to  0 

ctllnvis 

bit  7 

1-invisible,  0=visible 

Reserved 

bits  1-6 

Must  be  set  to  0 

fCallWindowMgr 

bitO 

1-call  GrowWindow  and  SizeWindow  to  track 

this  control 

0-just  highlight  control 
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Defined  bits  formoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  4-10 

Color  table  reference 

bits  2-3 

Reserved 


bits  0-1 


Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef 

(see  "Error  Corrections"  earlier  in  this  chapter 

for  the  definition  of  the  size  box  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
Must  be  set  to  0 
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Static  text  control  template 

Figure  28-16  shows  the  template  that  defines  a  static  text  control.  For  more  information 
about  static  text  controls,  see  "Static  text  control"  in  this  chapter. 


Figure  28-16    Control  template  for  static  text  controls 


$00 

- 

pCount 

- 

$02 

_ 

_ 

- 

ID 

- 

— 

$06 

rect 

$0E 

— 

— 

procRef 

- 

— 

$12 

flag 

- 

$14 

moreFlags 

- 

$16 

_ 

re f Con 

- 

— 

$1A 

_ 

text Re f 

- 

— 

$1E 

•textsize 

- 

$20 

*just 

- 

Word— Parameter  count  for  template:  7, 8,  or  9 
Long— Application-assigned  control  ID 

\  Rectangle— Boundary  rectangle  for  control 

Long— statTextControl  =$81000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 

Long— Reference  to  text  for  control 

Word— Text  size  field  (optional) 

Word— Initial  justification  for  text  (optional) 


Defined  bits  for  flag  are 


Reserved 

bits  8-15 

Must  be  set  to  0 

ctllnvis 

bit  7 

1 -invisible,  Ovisible 

Reserved 

bits  2-6 

Must  be  set  to  0 

fSubstituteText 

bitl 

0=no  text  substitution  to  perform 
l=there  is  text  substitution  to  perform 

fSubTextType 

bitO 

0=C  strings 
l»=Pascal  strings 
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Defined  bits  formoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  2-10 

Text  Reference 

bits  0-1 

textSize 


just 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 
Defines  type  of  text  reference  in  text  Re  f : 

00  -  text  reference  is  pointer 

01  -  text  reference  is  handle 

10  -  text  reference  is  resource  ID 
11 -invalid  value 

The  size  of  the  referenced  text  in  characters,  but  only  if  the  text 
reference  in  text  Re  f  is  a  pointer.  If  the  text  reference  is  either  a 
handle  or  a  resource  ID,  then  the  Control  Manager  can  extract  the 
length  from  the  handle. 

The  justification  word  is  passed  on  to  LETextBox2  (see 
Chapter  10,  lineEdit  Tool  Set,"  in  Volume  1  of  the  Toolbox  Reference 
for  details  on  the  LETextBox2  tool  call),  and  is  used  to  set  the  initial 
justification  for  the  text  being  drawn.  Valid  values  for  just  are 


leftJustify  0 

centerJustify  1 

rightJustify  -1 

fullJustify  2 


Text  is  left  justified  in  the  display  window 
Text  is  centered  in  the  display  window 
Text  is  right  justified  in  the  display  window 
Text  is  fully  justified  (both  left  and  right)  in 
the  display  window 


Static  text  controls  do  not  support  color  tables.  In  order  to  display  text  of  different 
color,  you  must  embed  the  appropriate  commands  into  the  text  string  you  are  displaying. 
See  the  discussion  of  LETextBox2  in  Chapter  10,  "LineEdit  Tool  Set,"  in  Volume  1  of  the 
Toolbox  Reference  for  details  on  command  format  and  syntax. 
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TextEdit  control  template 

Figure  28-17  shows  the  template  that  defines  a  TextEdit  control.  For  more  information 
about  TextEdit  controls,  see  TextEdit  control"  in  this  chapter. 


Figure  28-17    Control  template  for  TextEdit  controls 


$00 
$02 

$06 
$0E 

$12 

$14 
$16 

$1A 

$1E 
$26 

$2A 
$2C 

$30 


pcount  -   Word— Parameter  count  for  template:  7  to  23 

Long— Application-assigned  control  ID 


Rectangle— Boundary  rectangle  for  control 


—  moreFlags 


procRef  -    Long— editTextControl=$85000000 


nag  -   Word— Highlight  and  control  flags  for  control 

Word— Additional  control  flags 


refCon 


Long— Application-defined  value 


textnags        -   Long— Specific  TextEdit  control  flags  (see  below) 


•indentRect         '•  Rectangle— Defines  text  indentation  from  control  rect  (optional) 


*vertAmount    — 


•horzAmount 


continued 


•vertBar         -|  Long— Handle  to  vertical  scroll  bar  for  control  (optional) 
Word— Vertical  scroll  amount,  in  pixels  (optional) 

•horzBar         -|  Long— Reserved;  must  be  set  to  N1LL  (optional) 
Word— Reserved;  must  be  set  to  0  (optional) 
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continued 

$32 

—            *styleRef           — 

$36 

—     *textDescriptor     — 

$38 

-             *textRef            — 

$3C 

—         *textLength         — 

$40 

—            *maxChars            — 

$U 

—            *maxLines           — 

$48 

—  *maxCharsPerLines  — 

$4A 

—           *maxHeight          — 

$4C 

—            *colorRef           — 

$50 

—            *drawMode           — 

$52 

—      *filterProcPtr      - 

-  Long— Reference  to  initial  style  information  for  text  (optional) 

-  Word— Defines  format  of  initial  text  and  textRef  (optional) 

-  Long— Reference  to  initial  text  for  edit  window  (optional) 

-  Long— Length  of  initial  text  (optional) 

-  Long— Maximum  number  of  characters  allowed  (optional) 

Long— Reserved;  must  be  set  to  0  (optional) 

Word— Reserved;  must  be  set  to  0  (optional) 
Word— Reserved;  must  be  set  to  0  (optional) 

Long— Reference  to  TextEdit  color  table  (optional) 

-I  Word— QuickDraw  II  text  mode  for  edit  window  (optional) 

-  Long— Pointer  to  filter  routine  for  this  control  (optional) 


Defined  bits  for  flag  are 


Reserved 

bits  8-15 

Must  be  set  to  0 

ctllnvis 

bit  7 

1 -invisible,  0-visible 

Reserved 

bits  0-6 

Must  be  set  to  0 
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Defined  bits  for  moreFi 

3gs  are 

fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fTellAboutSize 

bit  11 

fCtllsMultiPart 

bit  10 

Reserved 

bits  4-9 

Color  table  reference 

bits  2-3 

Style  reference 


bits  0-1 


Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  1 

Must  be  set  to  1 

If  set  to  1,  a  size  box  will  be  created  in  the 

lower-right  corner  of  the  window.  Whenever  the 

control  window  is  resized,  the  edit  text  will  be 

resized  and  redrawn. 

Must  be  set  to  1 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorRef ;  the 

color  table  for  a  TextEdit  control 

(TECoiorTabie)  is  described  in 

Chapter  49,  "TextEdit,"  in  this  book: 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11 -invalid  value 

Defines  type  of  style  reference  in  styieRef ; 

the  format  for  a  TextEdit  style  descriptor  is 

described  in  Chapter  49,  TextEdit,"  in  this 

book: 

00  -  style  reference  is  pointer 

01  -  style  reference  is  handle 

10  -  style  reference  is  resource  ID 
11 -invalid  value 


A  Important 


Do  not  set  f  TeliAboutsize  to  1  unless  the  control  also  has  a 
vertical  scroll  bar.  a 


Valid  values  for  textFiags  are 


fNotControl 

bit  31 

Must  be  set  to  0 

fSingleFormat 

bit  30 

Must  be  set  to  1 

fSingleStyle 

bit  29 

Allows  you  to  restrict  the  style  options  available 

to  the  user: 

1  -  Allow  only  one  style  in  the  text 

0  -  Do  not  restrict  the  number  of  styles  in  the 

text 
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fNoWordWrap 


bit  28 


fNoScroll 


fReadOnly 


bit  27 


bit  26 


fSmartCutPaste 


bit  25 


fTabSwitch 


fDrawBounds 


bit  24 


bit  23 


fColorHilight 
fGrowRuler 


bit  22 
bit  21 


fDisableSelection        bit  20 


Allows  you  to  control  TextEdit  word  wrap 

behavior: 

1  -  Do  not  word  wrap  the  text;  only  break  lines 

on  CR  (SOD)  characters 

0  -  Perform  word  wrap  to  fit  the  ruler 
Controls  user  access  to  scrolling: 

1  -  Do  not  allow  either  manual  or  auto-scrolling 

0  -  Scrolling  permitted 

Restricts  the  text  in  the  window  to  read-only 
operations  (copying  from  the  window  will  still 
be  allowed): 

1  -  No  editing  allowed 

0  -  Editing  permitted 

Controls  TextEdit  support  for  smart  cut  and 
paste  (see  Chapter  49,  "TextEdit,"  for  details 
on  smart  cut  and  paste  support): 

1  -  Use  smart  cut  and  paste 

0  -  Do  not  use  smart  cut  and  paste 
Defines  behavior  of  the  Tab  key  (see 
Chapter  49,  "TextEdit,"  for  details): 

1  -  Tab  to  next  control  in  the  window 

0  -  Tab  inserted  in  TextEdit  document 

Tells  TextEdit  whether  to  draw  a  box  around  the 
edit  window,  just  inside  rect;  the  pen  for  this 
box  is  two  pixels  wide  and  one  pixel  high 

1  -  Draw  rectangle 

0  -  Do  not  draw  rectangle 
Must  be  set  to  0. 

Tells  TextEdit  whether  to  resize  the  ruler  in 
response  to  the  user  resizing  the  edit  window;  if 
set  to  1,  TextEdit  will  automatically  adjust  the 
right  margin  value  for  the  ruler: 

1  -  Resize  the  ruler 

0  -  Do  not  resize  the  ruler 
Controls  whether  user  can  select  text: 

1  -  User  cannot  select  text 
0  -  User  can  select  text 
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fDrawInactiveSelection 

bit  19 


Reserved 


indentRect 


vertBar 


vert Amount 

horzBar 
ho rz Amount 
styleRef 


bits  0-18 


Controls  how  inactive  selected  text  is 

displayed: 

1  -  TextEdit  draws  a  box  around  inactive 

selections 

0  -  TextEdit  does  not  display  inactive 

selections 

Must  be  set  to  0 


Each  coordinate  of  this  rectangle  specifies  the  amount  of  white  space 
to  leave  between  the  boundary  rectangle  for  the  control  and  the  text 
itself,  in  pixels.  Default  values  are  (2,6,2,4)  in  640  mode  and  (2,4,2,2) 
in  320  mode.  Each  indentation  coordinate  may  be  specified 
individually.  In  order  to  assert  the  default  for  any  coordinate,  specify 
its  value  as  $FFFF. 

Handle  of  the  vertical  scroll  bar  to  use  for  the  TextEdit  window.  If  you 
do  not  want  a  scroll  bar  at  all,  then  set  this  field  to  NIL.  If  you  want 
TextEdit  to  create  a  scroll  bar  for  you,  just  inside  the  right  edge  of  the 
boundary  rectangle  for  the  control,  then  set  this  field  to  $FFFFFFFF. 

Specifies  the  number  of  pixels  to  scroll  whenever  the  user  presses  the 
up  or  down  arrow  on  the  vertical  scroll  bar.  Iaorder  to  use  the  default 
value  (9  pixels),  set  this  field  to  $0000. 

Must  be  set  to  NIL. 

Must  be  set  to  0. 

Reference  to  initial  style  information  for  the  text.  See  the  description 
of  the  TEFormat  record  in  Chapter  49,  "TextEdit,"  for  information 
about  the  format  and  content  of  a  style  descriptor.  Bits  1  and  0  of 
moreFiags  define  the  type  of  reference  (pointer,  handle,  resource 
ID).  To  use  the  default  style  and  ruler  information,  set  this  field  to 
NULL. 


textDescriptor 

Input  text  descriptor  that  defines  the  reference  type  for  the  initial 
text  (which  is  in  textRef )  and  the  format  of  that  text.  See 
Chapter  49,  "TextEdit,"  for  detailed  information  on  text  and 
reference  formats. 

textRef  Reference  to  initial  text  for  the  edit  window.  If  you  are  not  supplying 

any  initial  text,  then  set  this  field  to  NULL. 
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textLength        If  text  Re  f  is  a  pointer  to  the  initial  text,  then  this  field  must  contain 
the  length  of  the  initial  text.  For  other  reference  types,  TextEdit 
extracts  the  length  from  the  reference  itself. 

♦    Note:  You  must  specify  or  omit  the  textDescriptor,  textRef ,  and  textLength 
fields  as  a  group. 

maxChars  Maximum  number  of  characters  allowed  in  the  text.  If  you  do  not  want 

to  define  any  limit  to  the  number  of  characters,  then  set  this  field  to 
NULL. 

maxLines  Must  be  set  to  0. 

maxCharsPerLines 

Must  be  set  to  NULL. 

maxHeight  Must  be  set  to  0. 

coiorRef  Reference  to  the  color  table  for  the  text.  This  is  a  Text  Edit  color  table 

(see  Chapter  49,  "TextEdit,"  for  format  and  content  of 
TECoiorTabie).  Bits  2  and  3  of  moreFiags  define  the  type  of 
reference  stored  here. 

drawMode  This  is  the  text  mode  used  by  QuickDraw  II  for  drawing  text.  See 

Chapter  16,  "QuickDraw  n,"  in  Volume  2  of  the  Toolbox  Reference  for 
details  on  valid  text  modes. 

filterProcPtr  Pointer  to  a  filter  routine  for  the  control.  See  Chapter  49,  "TextEdit," 
for  details  on  TextEdit  generic  filter  routines.  If  you  do  not  want  to 
use  a  filter  routine  for  the  control,  set  this  field  to  NIL. 
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Control  Manager  code  example 

This  section  contains  an  example  of  how  to  create  a  list  of  controls  for  a  window  with  a 
single  NewControi2  call.  If  you  wish  to  try  this  in  your  own  program,  you  will  need  to 
create  a  window  that  is  160  lines  high  and  600  pixels  wide. 

Equates  for  the  new  control  manager  features 
ctlMoreFlags 


fCtlTarget 

equ 

$8000 

fCtlCanBeTarget 

equ 

$4000 

fCtlWantEvents 

equ 

$2000 

fCtlProcRefNotPtr 

equ 

$1000 

fCtlTellAboutSize 

equ 

$0800 

titlelsPtr 

equ 

$0000 

titlelsHandle 

equ 

$0001 

titlelsResource 

equ 

$0002 

colorTablelsPtr 

equ 

$0000 

colorTablelsHandle 

equ 

$0004 

colorTablelsResource 

equ 

$0008 

NewControl2  ProcRef  values  for  standard  control  types 


simpleButtonControl 

equ 

$80000000 

checkControl 

equ 

$82000000 

radioControl 

equ 

$84000000 

scrollBarControl 

equ 

$86000000 

growControl 

equ 

$88000000 

statTextControl 

equ 

$81000000 

editLineControl 

equ 

$83000000 

editTextControl 

equ 

$85000000 

popUpControl 

equ 

$87000000 

listControl 

equ 

$89000000 

iconButtonControl 

equ 

$07FF0001 

pictureControl 

equ 

$8D000000 
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Here  is  the  definition  of  my  control  list,  note  it  is  simply  a  list 
of  pointers.  These  do  not  have  to  be  in  any  special  order.  This  list 
should  always  be  terminated  with  a  zero. 


MyControls  dc.L  theButton,theScroll,theCheck 
dc.L  Radiol, Radio2, StatControl 
dc.L  LEditControl,PopUp, IconButton, 0 


Scroll  bar  color  table  as  defined  by  the  original  control  manager. 
The  structure  of  these  tables  has  not  changed  for  the  existing 
control  types. 


MyColorTable 


dc.w  0 
dc.W  $00F0 

dc.W  $0005 
dc.W  $00F0 
dc.W  $00F0 
dc.W  $0000 
dc.W  $0030 

dc.W  $00F0 


outline  color 

arrow  unhilited  black  on 

white 
arrow  hilite  blue  on  black 
arrow  Background  color 
Thumb  unhilited 
Thumb  hilited 
Page  region  solid 

black/white 
Inactive  bar  color 


Definition  of  a  simple  vertical  scroll  bar 


theScroll   dc.W  10 
dc.L  1 

dc.W  10,10,110,36 
dc.L  scrollBarControl 
dc.W  3 

dc.W  fCtlProcRefNotPtr 

dc.L  0 

dc.W  100 

dc.W  10 

dc.W  5 

dc.L  MyColorTable 


number  of  parms 
application  ID 
rectangle 

scrollbar  def  proc 
vertical  scroll  bar  w/ 

arrows 
set  procnotptr  flag 
refcon 
max  size 
size  of  view 
initial  value 
color  table  to  use 
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Definition  of  a  simple  button 


SimpTitle 
theButton 


num  params 

app  ID 

a  25x30  button 

;  simple  button 
visible,  round  corner 


str  'Button' 

dc.W  7 

dc.L  2 

dc.W  10,40,0,0 

dc.L  simpleButtonControl 

dc.W  0 

dc . W  f CtlProcRef NotPtr+f CtlWantEvents 

dc.L  0 

dc.L  simpTitle  ;  button  Title 


Definition  of  a  check  box  control 


CheckTitle  str  'CheckBox' 
theCheck    dc.W  8 

dc.L  3 

dc.W  25,40,0,0 

dc.L  checkControl 

dc.W  0 

dc.W  f CtlProcRef NotPtr 

dc.L  0 

dc.L  CheckTitle 

dc.W  0 


num  params 
app  ID 

bounding  rect 
control  type 
flags 
MoreFlags 
Re f Con 
TitlePointer 


Definition  of  a  radio  button  control 


RadiolTitle  str  'Radiol' 
Radiol      dc.W  8 

dc.L  4 

dc.W  45,40,0,0 

dc.L  radioControl 

dc.W  1 

dc.W  f CtlProcRef NotPtr 

dc.L  0 

dc.L  RadiolTitle 

dc.W  1 
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Definition  of  another  radio  button  control 

Radio2Title  str  'Radio2' 
Radio2      dc.W  8 

dc.L  5 

dc.W  65,40,0,0 

dc.L  radioControl 

dc.W  1 

dc.W  fCtlProcRefNotPtr 

dc.L  0 

dc.L  Radio2Title 

dc.W  0 

Definition  of  a  static  text  control 

StatTitle   dc.B  'This  is  Stat  Text' 
StatControl  dc.W  8 

dc.L  6 

dc.W  120,10,135,210 

dc.L  statTextControl 

dc.W  0 

dc.W  fCtlProcRefNotPtr 

dc.L  0 

dc.L  StatTitle 

dc.W  17 


Definition  of  an  edit  line  control 


EditDefault  str  'Def aultText" 
LEditControl 

dc.W  8 

dc.L  7 

dc.W  120,240,135,440 

dc.L  editLineControl 

dc.W  0 

dc.W  fCtlProcRefNotPtr 

dc.L  0 

dc.W  30 

dc.L  EditDefault 
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Definition  of  a  pop  up  menu  control  (and  its  menu) 

PopUpMenu   dc.B  ' $$PopUpMenu: \N6' , $00 

dc.B  '--Selection  1\N259',$00 
dc.B  ' — Selection  2\N260',$00 
dc.B  ' — Selection  3\N261',$00 
dc.B  '--Selection  4\N262',$00 
dc.b  ' . ' 


Popup 


dc.w  9 

dc.L  8 

dc.W  25,140,40,380 

dc .  L  popUpCont'rol 

dc.W  0 

dc.W  fCtlProcRefNotPtr+fMenuDeflsText 

dc.L  0 

dc.W  100 

dc.L  PopUpMenu 

dc.W  259  ;  initial  value 


Definition  of  an  icon  button  control 


IconButtonTitle 

str  'Icon  Button' 


Icon 


dc.w  0 
dc.w  200 
dc.w  10 
dc . w  40 


; black  and  white  icon 

; icon  height  in  pixels 
;icon  width  in  pixels 
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;    Data   for  icon  goes   here    (omitted) 


IconButton 


dew   10 

ds.l   1 

dew    40,40,80,100 

del   iconButtonControl 

dew   0 

dew  FctlProcRefNotPtr 

del   0 

del   Icon 

del   IconButtonTitle 

del  MyColorTable 
dew   0 


pCount 

ID 

button  rectangle 

defproc 

single  outline, 

round-cornered 
get  defproc  from 

resource 

pointer  to  icon 
pointer  to  p-string 

title 
pointer  to  color  table 
standard  drawing  of  icon 


To  create  the  above  new  controls  in  a  window  use  the  NewControl2  call: 


pha 

pha 

PushLong  WindPointer 

PushWord  #ptrToPtr 

PushLong  #MyControls 

_NewControl2 

pla 

pla 


room  for  result 

Pointer  to  Owner  window 
Input  verb  for  ptr  to  table 
pointer  to  table  of  templates 

discard  these  bytes,  only  verb 
for  single  ctl  returns  a  value 
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New  control  records 

The  NewControi2  tool  call  creates  extended  control  records  (as  discussed  earlier  in  this 
chapter  in  "New  and  changed  controls").  This  section  describes  the  format  and  content  of 
the  control  records  created  by  NewControi2. 

A  Warning         All  control  record  layouts  and  field  descriptions  are  provided  so  that 
programs  may  read  these  records  for  needed  information.  Your 
program  should  never  set  values  into  control  records. a 


Generic  extended  control  record 

Currently,  the  Control  Manager's  standard,  or  generic,  control  record  is  $28  bytes  long  (see 
Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for  information  about 
existing  control  records).  To  support  the  new  controls  (those  created  with 
NewControi2),  the  generic  control  record  has  several  new  fields.  The  layout  of  the  new 
generic  control  record  follows. 
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Figure  28-18    Generic  extended  control  record 


$00 


$04 


$08 


—  ctlNext 


—  ctlOwner  —    Long 


Long 


ctiRect  j  Rectangle 


Byte 
Byte 

Word 


$10 

ctlFXag 

$11 

ctlHilite 

$12 

ctlValue 

- 

$14 

— 

ctlProc 

- 

— 

$18 

— 

ctlAction 

- 

— 

$1C 

ctlData 

: 

— 

$20 

— 

ctlRefCon 

- 

— 

$24 

_ 

ctlColor 

- 

- 

$28 

-   Long 


Long 


Long 


Long 


Long 


ctiReserved       :  Block,  $10  bytes 


$38 


$3C 


ctiiD  —   Long 


ctlMoreFlags       -    Word 


^E  -        ctlVersion        -    Word 
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ctlNext 


ctlOwner 
ctlRect 

ctlFlag 

ctlHilite 


ctlValue 


A  handle  to  the  next  control  associated  with  this  control's  window.  All 
the  controls  belonging  to  a  given  window  are  kept  in  a  linked  list, 
beginning  in  the  wcontroi  field  of  the  window  record  and  chained 
together  through  the  ctlNext  fields  of  the  individual  control 
records.  The  end  of  the  list  is  marked  by  a  zero  value;  as  new  controls 
are  created,  they're  added  to  the  beginning  of  the  list. 

A  pointer  to  the  window  port  to  which  the  control  belongs. 

The  rectangle  that  defines  the  control's  position  and  size  in  the  local 
coordinates  of  the  control's  window. 

A  bit  flag  that  further  describes  the  control.  The  appropriate  values  are 
shown  for  each  control  in  the  sections  that  follow. 

Specifies  whether  and  how  the  control  is  to  be  highlighted  and 
indicates  whether  the  control  is  active  or  inactive.  This  field  also 
specifies  whether  the  control  wants  to  receive  selection  events.  The 
values  for  ctlHilite  are  as  follows: 


0 


1-254 
255 


Control  active;  no  highlighted  parts— this  value  will  cause 

events  to  be  generated  when  the  mouse  button  is  pressed  in 

the  control 

Part  code  of  a  highlighted  part  of  the  control 

Control  inactive— this  value  indicates  that  no  events  are  to 

be  generated  when  the  mouse  button  is  pressed  in  the 

control 


Only  one  part  of  a  control  can  be  highlighted  at  any  one  time,  and  no 
part  can  be  highlighted  on  an  inactive  control.  See 
Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for 
more  information  on  highlighting. 

The  control's  current  setting.  For  check  boxes  and  radio  buttons,  zero 
means  the  control  is  off,  and  a  nonzero  value  means  if  s  on.  For  scroll 
bars,  the  value  is  between  0  and  the  data  size  minus  the  view  size.  The 
field  is  also  available  for  custom  controls  to  use  as  appropriate. 
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ctlProc 


ctlAction 


ctlData 


For  standard  controls,  this  field  indicates  the  control  type,  identified 
by  its  ID.  For  custom  controls,  this  field  contains  a  pointer  to  the 
control  definition  procedure  (defProc)  for  this  type  of  control. 

For  controls  created  with  NewControi,  valid  ID  values  are: 


simpleProc 

checkProc 

radioProc 

scrollProc 

growProc 


$00000000  Simple  button 

$02000000  Check  box 

$04000000  Radio  button 

$06000000  Scroll  bar 

$08000000  Size  box 


ctlRefCon 


For  controls  created  with  NewControi2,  the  f  ctiProcRef  NotPtr 
flag  in  ctiMoreFiags  allows  the  Control  Manager  to  discriminate 
between  pointers  and  IDs.  Valid  ID  values  (used  with 
f  CtiProcRef  NotPtr  set  to  1)  are: 

simpieButtonControi  $80000000  Simple  button 

checkcontroi  $82000000  Check  box 

iconButtonControl  $07FF0001  Icon  button 

editLineControi  $83000000  LineEdit 

listcontroi  $89000000  List 

pictureControi  $8D000000  Picture 

popUpControl  $87000000  Pop-up 

radiocontroi  $84000000  Radio  control 

scroiiBarControi  $86000000  Scroll  bar 

growControl  $88000000  Size  box 

statTextControl  $81000000  Static  text 

editTextControi  $85000000  TextEdit 

Pointer  to  the  control's  custom  action  procedure,  if  any. 
Trackcontroi  may  call  the  custom  action  procedure  to  respond  to 
the  user  dragging  the  mouse  inside  the  control.  See 
Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for 
more  information  about  Trackcontroi. 

Reserved  for  use  by  the  control  definition  procedure,  typically  to  hold 
additional  information  for  a  particular  control  type.  For  example,  the 
standard  definition  procedure  for  scroll  bars  uses  the  low-order  word 
as  the  view  size  and  the  high-order  word  as  the  data  size.  The  standard 
definition  procedures  for  simple  buttons,  check  boxes,  and  radio 
buttons  store  the  address  of  the  control's  title. 

This  field  is  reserved  for  application  use. 
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ctlColor 


ctlReserved 


ctllD 


ctlMoreFlags 


fCtlTarget 

$8000 

fCtlCanBeTarget 

$4000 

fCtlWantEvents 

$2000 

This  field  contains  a  reference  to  the  color  table  to  use  when  drawing 
the  control.  If  the  field  is  set  to  NIL,  the  Control  Manager  uses  a 
default  color  table  defined  by  the  control's  definition  procedure. 
Otherwise,  ctlColor  contains  a  pointer,  handle,  or  resource  ID  for 
the  color  table  to  use.  Bits  2  and  3  of  ctlMoreFlags  usually  allow 
the  Control  Manager  to  discriminate  between  these  different  data 
types. 

This  space  is  reserved  for  use  by  the  control  definition  procedure.  In 
some  cases,  the  use  is  prescribed  by  the  system.  For  example, 
keyboard  equivalent  information  is  stored  here  for  controls  that 
support  keyboard  equivalents. 

This  field  may  be  used  by  the  application  to  provide  a  straightforward 
mechanism  for  keeping  track  of  controls.  The  control  ID  is  a  value 
assigned  by  your  application  with  the  id  field  of  the  control  template 
used  to  create  the  control.  Your  application  can  use  the  ED,  which  has 
a  known  value,  to  identify  a  particular  control. 

This  field  contains  bit  flags  that  provide  additional  control 
information  needed  for  new-style  controls  (those  created  with 
NewControi2).  You  can  use  the  GetctiMoreFiags  Control 
Manager  call  to  read  the  value  of  this  field  from  a  specified  control 
record.  Use  the  SetctiMoreFiags  call  to  change  the  value. 

The  high-order  byte  is  used  by  the  Control  Manager  to  store  its  own 
control  information.  The  low-order  byte  is  used  by  the  control 
definition  procedure  to  define  reference  types. 

The  defined  Control  Manager  flags  are: 

If  set  to  1,  this  control  is  currently  the  target  of 

any  typing  or  editing  commands. 

If  set  to  1  then  this  control  can  be  made  the 

target  control. 

If  set  to  1  then  this  control  can  be  called  when 

events  are  passed  via  the  sendEventTocti 

Control  Manager  call.  Note  that,  if  the 

fCtlCanBeTarget  flag  is  set  to  1,  this  control 

will  receive  events  sent  to  it  regardless  of 
setting  of  this  flag. 


Chapter  28    Control  Manager  Update     28-93 


Apple  JIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1 989 


fCtlProcRefNotPtr 


fCtlTellAboutSize 


fCtllsMultiPart 


$1000  If  set  to  1,  then  Control  Manager  expects 

ctiProc  to  contain  the  ID  of  a  standard 
control  procedure.  If  set  to  0,  then  c  tip  roc 
contains  a  pointer  to  the  custom  control 
procedure. 

$0800  If  set  to  1,  then  this  control  needs  to  be 

notified  when  the  size  of  the  owning  window 
has  changed.  This  flag  allows  custom  control 
procedures  to  resize  their  associated  control 
images  in  response  to  changes  in  window  size. 

$0400  If  set  to  1,  then  this  is  a  multipart  control.  This 

flag  allows  control  definition  procedures  to 
manage  multi-part  controls  (necessary  since  the 
Control  Manager  does  not  know  about  all  the 
parts  of  a  multi-part  control). 

The  low-order  byte  uses  the  following  convention  to  describe 
references  to  color  tables  and  titles  (note,  though,  that  some  control 
templates  do  not  follow  this  convention): 


titlelsPtr 

$00 

Title  reference  is  by  pointer 

titlelsHandle 

$01 

Title  reference  is  by  handle 

titlelsResource 

$02 

Title  reference  is  by  resource  ID 

colorTablelsPtr  $00 
colorTablelsHandle  $04 
colorTablelsResource  $08 


Color  table  reference  is  by  pointer 
Color  table  reference  is  by  handle 
Color  table  reference  is  by  resource  ID 


ctiversion        This  field  is  reserved  for  future  use  by  the  Control  Manager  to 
distinguish  between  different  versions  of  control  records. 
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Extended  simple  button  control  record 

Figure  28-19  shows  the  format  of  the  extended  control  record  for  simple  button  controls. 
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Figure  28-19    Extended  simple  button  control  record 


$00 


$04  _ 


$08 


$10 
$11 
$12 

$14 


$18 

$1C 

$20 

$24 

$28 
$2E 
$38 

$3C 

$3E 


ctlNext 


ctl Owner 


Long— Handle  to  next  control;  NIL  for  last  control 


Long— Pointer  to  window  to  which  control  belongs 


ctiRect  j  Rectangle— Defines  button's  boundary  rectangle 


ctlFlag 


ctlHilite 


ct lvalue 


ctlProc 


ctlActlon 


ctlColor 


Byte— Defines  button  style 
Byte— Current  type  of  highlighting 

Word— Not  used;  set  to  0 

Long— sin^leButtonControl=$80000000 


Long— Pointer  to  custom  procedure;  ML  if  none 


ctioata  -   Long— Reference  to  button  title  string 


ctiRefcon        -   Long— -Reserved  for  application  use 


Long— Optional  color  table  reference;  NIL  if  none 


iteyEquiv  \  Block,  $06  Bytes— Key  equivalent  record 


ctiReserved         :  Block,  $0A  bytes— Reserved 


ctiiD  -  Long-rApplication-assigned K) 


ctlMoreFlags 


—  ctlVerslon 


Word— Additional  control  flags 
Word— Set  to  0 


28-96     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Valid  values  for  ctiFiag  are 


ctllnvis 

bit  7 

Reserved 

bits  2-6 

Button  type 

bits  0-1 

Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  4-10 

Color  table  reference 

bits  2-3 

Title  reference 


bits  0-1 


1 -invisible,  0=visible 
Must  be  set  to  0 
Describes  button  type: 

0  -  single-outlined  round-cornered  button 

1  «=  bold-oudined  round-cornered  button 

2  ■  single-outlined  square-cornered  button 

3  -  single-outlined  square-cornered  drop- 
shadowed  button 


Must  be  set  to  0 

Must  be  set  to  0 

Set  to  1  if  button  has  keystroke  equivalent 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  incticoior(ifitis 

not  NIL).  See  Chapter  4,  "Control  Manager,"  in 

Volume  1  of  the  Toolbox  Reference  for  the 

definition  of  the  simple  button  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  tide  reference  in  ctlData: 

00  -  tide  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  tide  reference  is  resource  ID 
11 -invalid  value 


keyEquiv 


Keystroke  equivalent  information  stored  at  keyEquiv  is  formatted 
as  shown  in  Figure  28-2. 
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Extended  check  box  control  record 

Figure  28-20  shows  the  format  of  the  extended  control  record  for  check  box  controls. 
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Figure  28-20    Extended  check  box  control  record 


ctiNext  -   Long— Handle  to  next  control;  NIL  for  last  control 


$2E 
$38 

$3C 
$3E 


-   Long— Pointer  to  window  to  which  control  belongs 


ctiRect  \  Rectangle— Defines  check  box's  boundary  rectangle 


Byte— Defines  check  box  visibility 
Byte— Current  type  of  highlighting 

Word— 0  if  not  checked;  1  if  checked 
Long— checkControl  =$82000000 


Long— Pointer  to  custom  procedure;  NIL  if  rone 
Long— Reference  to  check  box  title  string 
Long— Reserved  for  application  use 

Long— Optional  color  table  reference;  NIL  if  none 
Block,  $06  Bytes— Key  equivalent  record 


$10 

ctlFlag 

$11 

ctlHilite 

$12 

ctlValue 

- 

$14 

_ 

ctlProc 

- 

— 

$18 

— 

ctlAction 

- 

— 

$1C 

_ 

ctlData 

- 

— 

$20 

_ 

ctlRefCon 

: 

$24 

_ 

ctlColor 

- 

— 

$28 

keyEquiv 


ctiReserved         '■  Block,  $0A  bytes— Reserved 


ctllD 


ctlMoreFlags    — 


—     ctlVersion 


Long— Application-assigned  ID 

Word— Additional  control  flags 
Word— Set  toO 
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Valid  values  for  ctiFlag  are 


ctllnvis 

Reserved 


bit  7 
bits  0-6 


Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

Reserved 

Color  table  reference 


Title  reference 


bit  15 
bit  14 
bit  13 
bit  12 
bit  11 
bits  4-10 
bits  2-3 


bits  0-1 


l=invisible,  0=visible 
Must  be  set  to  0 


Must  be  set  to  0 

Must  be  set  to  0 

Set  to  1  if  check  box  has  keystroke  equivalent 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  incticoior(ifitis 

not  NIL).  See  Chapter  4,  "Control  Manager,"  in 

Volume  1  of  the  Toolbox  Reference  for  the 

definition  of  the  check  box  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  tide  reference  in  ctiData: 

00  -  title  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  ID 
11 -invalid  value 


keyEquiv 


Keystroke  equivalent  information  stored  at  keyEquiv  is  formatted 
as  shown  in  Figure  28-2. 
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Icon  button  control  record 

Figure  28-21  shows  the  format  of  the  control  record  for  icon  button  controls. 

■    Figure  28-21    Icon  button  control  record 


Long— Handle  to  next  control;  NIL  for  last  control 


ctiowner         -   Long— Pointer  to  window  to  which  control  belongs 


ctiRect  [  Rectangle— Defines  icon  boundary  rectangle 


Byte— Defines  control  visibility  and  button  style 
Byte— Controls  highlighting 

Word— Not  used;  set  to  0 
-    Long— iconButtonControl=$07FF0001 


Long— Pointer  to  custom  procedure;  NIL  if  none 


Long— Optional  reference  to  title  string  for  button 


-  Long— Reserved  for  application  use 


-   Long— Optional  color  table  reference;  NIL  if  none 


keyEquiv  :  Block,  $06  bytes— Key  equivalent  record 


$10 

ctlFlag 

$11 

ctlHillte 

$12 

ctlValue 

- 

$14 

_ 

ctlProc 

- 

— 

$18 

_ 

ctlAction 

- 

- 

$1C 

— 

— 

ctlData 

- 

— 

$20 

— 

ctlRefCon 

- 

— 

$24 

_ 

ctlColor 

- 

— 

$28 

continued 
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continued 

$2E 

ctlReserved 

Block,  $0A  bytes— Reserved 

$38 

-                ctllD 

- 

Long-^Application-assigned  ID 

$3C 

—         ctlMoreFlags 

Word— Additional  control  flags 

$3E 

—          ctlVersion 

- 

Word-Set  toO 

$40 

—              iconRef 

~ 

Long— Reference  to  icon 

$44 

—          displayMode 

- 

Word— Bit  flag  defining  icon's  appearance 

Valid  values  for  ctiFlag  are 


ctllnvis 

bit  7 

Reserved 

bits  3-6 

showBorder 

bit  2 

buttonType 

bits  0-1 

1 -invisible,  0- visible 
Must  be  set  to  0 
1-No  border,  0-Show  border 
Defines  button  type: 

00  -  single-outlined  round-cornered  button 

01  -  bold-oudined  round-cornered  button 

10  -  single-outlined  square-cornered  button 

11  -  single-outlined  square-cornered  and  drop- 
shadowed  button 
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Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  6-10 

Icon  reference 

bits  4-5 

Color  table  reference 


Title  reference 


bits  2-3 


ctlData 
displayMode 


keyEquiv 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 
Defines  type  of  icon  reference  in  iconRef : 

00  -  icon  reference  is  pointer 

01  -  icon  reference  is  handle 
10  -  icon  reference  is  resource  ID 
11 -invalid  value 

Defines  type  of  reference  incticoior(ifitis 
not  NIL).  The  color  table  for  an  icon  button  is 
the  same  as  that  for  a  simple  button.  See 
Chapter  4,  "Control  Manager,"  in  Volume  1  of 
the  Toolbox  Reference  for  the  definition  of  the 
simple  button  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 
10  -  color  table  reference  is  resource  ID 
11 -invalid  value 
Defines  type  of  tide  reference  in  ctlData: 

00  -  title  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  tide  reference  is  resource  ID 

11  -  invalid  value 

Holds  the  reference  to  the  tide  string,  which  must  be  a  Pascal  string. 

Passed  direcdy  to  the  Drawicon  routine,  and  defines  the  display 
mode  for  the  icon.  The  Control  Manager  sets  this  field  from  the 
displayMode  field  in  the  icon  button  control  template  used  to 
create  the  control. 

Keystroke  equivalent  information  stored  at  keyEquiv  is  formatted 
as  shown  in  Figure  28-2. 


bits  0-1 
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LineEdit  control  record 

Figure  28-22  shows  the  format  of  the  control  record  for  LineEdit  controls. 


Figure  28-22    LineEdit  control  record 


$00 

_ 

ctlNext 

- 

— 

$04 

— 

ctlOwner 

- 

— 

$08 

-   Long— Handle  to  next  control;  NIL  for  last  control 


-   Long— Pointer  to  window  to  which  control  belongs 


ctiRect  \  Rectangle— Defines  control  boundary  rectangle 


$10 
$11 
$12 


$14  _ 


$18  _ 


$1C 

$20 

$24 

$28 
$38 

$3C 
$3E 


ctlFlag 


ctlHllite 


ct lvalue 


ctlProc 


ctlActlon 


ctlColor 


Byte— Defines  control  visibility 
Byte— Controls  highlighting 

Word— Not  used;  must  be  set  to  0 
Long—  editLineControl=$83000000 

Long— Pointer  to  custom  procedure;  NIL  if  none 


ctioata         -  Long— Handle  to  LineEdit  edit  record 


ctiRefcon        -   Long— Reserved  for  application  use 


Long— Not  used;  must  be  set  to  0 


ctiReserved        :  Block,  $10  bytes— Not  used;  must  be  set  to  0 
Long— Application-assigned  ID 


CtllD 


ctlMoreFlags    — 


ctlVerslon     — 


Word— Additional  control  flags 
Word— Set  toO 
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Valid  values  for  ctiFlag  are 


ctllnvis 

bit  7 

1 -invisible,  0=visible 

Reserved 

bits  0-6 

Must  be  set  to  0 

Valid  values  for  ctiMore 

jFiags  are 

fCtlTarget 

bit  15 

Must  be  set  to  0 

fCtlCanBeTarget 

bit  14 

Must  be  set  to  1 

fCtlWantsEvents 

bit  13 

Must  be  set  to  1 

fCtlProcNotPtr 

bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11 

Must  be  set  to  0 

Reserved 

bits  2-10 

Must  be  set  to  0 

Text  reference 

bits  0-1 

Defines  type  of  text  reference  in  ctiData 

00  -  text  reference  is  pointer 

01  -  text  reference  is  handle 

10  -  text  reference  is  resource  ID 
11 -invalid  value 

ctiData 


Control  Manager  stores  the  handle  to  the  LineEdit  edit  record  in  the 
ctiData  field.  If  you  want  to  issue  LineEdit  tool  calls  directly,  you 
can  retrieve  the  handle  from  that  field. 


Note  that  LineEdit  controls  do  not  support  color  tables. 
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list  control  record 

Figure  28-23  shows  the  format  of  the  control  record  for  list  controls. 

■    Figure  28-23    List  control  record 


$00 


$04 


$08 


$10 
$11 
$12 

$14 


$18 

$1C 

$20 

$24 

$28 

$2C 
$2E 


ctlNext 


ctlOwner 


Long — Handle  to  next  control;  NIL  for  last  control 


Long— Pointer  to  window  to  which  control  belongs 


ctiRect  j  Rectangle— Defines  control  boundary  rectangle 


ctlFlag 


ctlHilite 


ctlValue 


ctlProc 


ctlData 


—     ctlRefCon     — 


ctlColor 


ct lMemDraw     — 


ctlMemHeight 


—     ctlMemSlze     — 


continued 


Byte— Defines  style  of  scroll  bar  for  list  window 
Byte— -Not  used;  must  be  set  to  0 

Word— Reserved 


Long— listControl  =$89000000 


-        ctiAction        -   Long— -Pointer  to  custom  procedure;  NIL  if  none 

Long— High-word  islistSize ;  low-word  is  viewSize 

Long— Reserved  for  application  use 

Long— Reference  to  the  color  table  for  the  control 


Long— Pointer  to  list  member  drawing  routine 

Word— List  member  height  in  pixels 
Word— List  member  record  size  in  bytes 
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continued 

$30 

_ 

ctlListRef 

- 

— 

$34 

_ 

ctlListBar 

- 

— 

$38 

_ 

ctllD 

- 

$3C 

— 

$3E 

ctlMoreFlags 

- 

ctlVersion 

- 

-   Long— Reference  to  list  member  records 
Long— Handle  of  control's  scroll  bar  control 

-|  Long— Application-assigned  ID 

Word— Additional  control  flags 
Word— Set  toO 


Valid  values  for  ctiFlag  are 


ctllnvis 
Reserved 


bit  7 
bits  0-6 


1 -invisible,  0=visible 
Must  be  set  to  0 
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Valid  values  tor  ctiMoreFiags  are 

fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

fCtllsMultiPart 

bit  10 

Reserved 

bits  4-9 

Color  table  reference 

bits  2-3 

List  reference 


bits  0-1 


Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  0 

Defines  type  of  reference  in  cticoior  (if  it  is 

not  NIL).  The  color  table  for  a  List  control  is 

described  in  Chapter  11,  "List  Manager,"  in 

Volume  1  of  the  Toolbox  Reference. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 
11 -invalid  value 

Defines  type  of  reference  in  listRef .  The 
format  for  a  list  member  record  is  described  in 
Chapter  11,  "List  Manager,"  in  Volume  1  of  the 
Toolbox  Reference. 

00  -  list  reference  is  pointer 

01  -  list  reference  is  handle 

10  -  list  reference  is  resource  ID 
11 -invalid  value 
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Picture  control  record 

Figure  28-24  shows  the  format  of  the  control  record  for  picture  controls. 

■    Figure  28-24    Picture  control  record 


$00 


$04 


$08 


$10 
$11 
$12 

$14 


$18 

SIC 

$20 

$24 

$28 
$38 

$3C 
$3E 


ct  iNext  -   Long— Handle  to  next  control;  NIL  for  last  control 


ctlOwner 


Long— Pointer  to  window  to  which  control  belongs 


ctiRect  j  Rectangle— Defines  picture  boundary  rectangle 


ctlFlag 


ctlHilite 


Byte— Defines  picture  visibility 

Byte— Controls  event  generation  for  control 

ct  lvalue         -j  Word— Not  used;  set  to  0 

ctiProc  H  Long— pictureControl=$8D000000 


ctlData 


—     ctlRefCon 


ctiAction        -   Long— Pointer  to  custom  procedure;  NIL  if  none 
Long— Reference  to  picture 
Long— Reserved  for  application  use 


cticoior         -   Long— -Not  used;  must  be  set  to  0 


ctiReserved         '■  Block,  $10  bytes— Not  used 

Long— Application-assigned  ID 


ctllD 


—    ctlMoreFlags 


—    ctlVerslon    — 


Word— Additional  control  flags 
Word— Set  to  0 
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Valid  values  for  ctiFlag  are 


ctllnvis 

bit  7 

1  "invisible,  0-visible 

Reserved 

bits  0-6 

Must  be  set  to  0 

Valid  values  for  ctiMoreFiags  are 

fCtlTarget 

bit  15 

Must  be  set  to  0 

fCtlCanBeTarget 

bit  14 

Must  be  set  to  0 

fCtlWantsEvents 

bit  13 

Must  be  set  to  0 

fCtlProcNotPtr 

bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11 

Must  be  set  to  0 

Reserved 

bits  2-10 

Must  be  set  to  0 

Picture  reference 

bits  0-1 

Define  type  of  picture  reference  inctiData 

00  -  invalid  value 

01  -  reference  is  handle 

10  -  reference  is  resource  DO 
11 -invalid  value 

ctiHiiite  Specifies  whether  the  control  wants  to  receive  mouse  events.  The 

values  for  ctiHiiite  are  as  follows: 

0      Events  will  be  generated  when  the  mouse  button  is  pressed  in  the 

control 
255   No  events  will  be  generated  when  the  mouse  buttron  is  pressed 

in  the  control 
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Pop-up  control  record 

Figure  28-25  shows  the  format  of  the  control  record  for  pop-up  menu  controls. 

■    Figure  28-25    Pop-up  control  record 


ctiNext  -   Long— Handle  to  next  control;  NIL  for  last  control 


ctiowner         -   Long— -Pointer  to  window  to  which  control  belongs 


ctiRect  I  Rectangle— Defines  control  boundary  rectangle 


Byte— Defines  control  visibility  and  other  attributes 
Byte— Not  used;  must  be  set  to  0 

Word— Currently  selected  item 
-   Long-popUpControl  =$87000000 


Long— Pointer  to  custom  procedure;  NIL  if  none 


-   Long— Jfot  used;  must  be  set  to  0 


Long— Reserved  for  application  use 


Long— Reference  to  the  color  table  for  the  control 


-   Long— Reference  to  menu  definition 


$10 

ctlFlag 

$11 

ctlHilite 

$12 

ct lvalue 

- 

$14 

— 

ctlProc 

- 

— 

$18 

— 

_ 

™ 

ctlAction 

: 

$1C 

_ 

ctlData 

- 

— 

$20 

_ 

ctlRefCon 

- 

— 

$24 

_ 

ctlColor 

~ 

$28 

_ 

menuRel 

- 

— 

continued 

Chapter  28-  Control  Manager  Update   28-111 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


$2C 

$30 

$38 

$3C 
$3E 
$40 


continued 


menuEnd 


ctllD 


Long— Must  be  set  to  0 


popupRect  j  Rectangle— Calculated  by  Menu  Manger 


—    ctlMoreFlags    — 


—    ctlVersion    — 


-     tltleWidth     - 


Long— Application-assigned  ID 

Word— Additional  control  flags 

Word— Set  toO 

Word— Pixel  width  of  title  position  of  menu 


Valid  values  for  ctiFiag  are 


ctllnvis 

bit  7 

1 -invisible,  0-visible 

fType2PopUp 

bit  6 

Indicates  type  of  pop-up  menu: 

1  -  Draw  pop-up  with  white  space  (Type  2) 

0  -  Draw  normal  pop-up 

fDontHiliteTitle 

bit  5 

Controls  highlighting  of  the  control  title: 

1  -  Do  not  highlight  title  when  control  is  popped 

up 

0  -  Highlight  title 

fDontDrawTitle 

bit  4 

Indicates  whether  the  Control  Manager  is  to 
draw  the  menu  tide: 
1  -  Do  not  draw  the  tide 
0  -  Draw  the  title 

fDontDrawResult 

bit  3 

Indicates  whether  result  is  shown: 

1  -  Do  not  draw  the  result  in  the  result  area  after 

a  selection 

0- Draw  the  result 
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flnWindowOnly 


bit  2 


fRightJustifyTitle  bit  1 


fRight JustifyResult  bit  0 


Controls  the  extent  to  which  the  pop-up  menu 

can  grow;  this  is  particularly  relevant  with 

respect  to  Type  2  pop-ups  (see 

Chapter  37,  "Menu  Manager  Update,"  for  details 

on  Type  2  pop-up  menus): 

1  -  Keep  the  pop-up  in  the  current  window 

0  -  Allow  the  pop-up  to  grow  to  screen  size 
Controls  title  justification: 

1  -  Right  justify  the  title;  note  that  if  the  title  is 
right  justified,  then  the  control  rectangle  is 
adjusted  to  eliminate  unneeded  pixels  (see 
Figure  28-12),  the  value  for  titiewidth  is  also 
adjusted 

0  -  Left  justify  the  title 
Controls  result  justification: 

1  -  Right  justify  the  selection 

0  -  Left  justify  the  selection  titiewidth 
pixels  from  the  left  of  the  pop-up  rectangle. 
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Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  5-10 

Color  table  reference 

bits  3-4 

fMenuDeflsText 


bit  2 


Menu  reference 


bits  0-1 


Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  1  if  the  pop-up  has  any 

keystroke  equivalents  defined 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef 

(the  color  table  for  a  menu  is  described  in 

Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the 

Toolbox  Reference) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11 -invalid  value 

Defines  type  of  data  referred  to  by  menuRef : 

I  -  menuRef  is  a  pointer  to  a  text  stream  in 
NewMenu  format  (see 

Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the 
Toolbox  Reference  for  details) 
0  -  menuRef  is  a  reference  to  a  Menu  Template 
(again,  see  Chapter  13,  "Menu  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  for  details  on 
format  and  content  of  a  Menu  Template) 
Defines  type  of  menu  reference  in  menuRef  (if 
fMenuDeflsText  is  set  to  1,  then  these  bits 
are  ignored): 

00  -  menu  reference  is  pointer 

01  -  menu  reference  is  handle 

10  -  menu  reference  is  resource  ID 

II  -  invalid  value 


28-114  Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


ctlRect 


ctlValue 
titleWidth 

menuRef 


Defines  the  boundary  rectangle  for  the  pop-up  and  its  tide,  before  the 
menu  has  been  "popped"  by  the  user.  The  Menu  Manager  will  calculate 
the  lower-right  coordinates  of  the  rectangle  for  you,  if  you  specify 
those  coordinates  as  (0,0). 

Contains  the  item  number  of  the  currendy  selected  item. 

Contains  the  value  set  in  the  titleWidth  field  of  the  pop-up  menu 
control  template  used  to  create  the  control. 

Reference  to  menu  definition  (see  Chapter  13,  "Menu  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  and 

Chapter  37,  "Menu  Manager  Update,"  in  this  book  for  details  on  menu 
templates).  The  type  of  reference  contained  in  menu  Re  f  is  defined 
by  the  Menu  reference  bits  in  ctiMoreFiags.  This  field  is  set  from 
the  menuRef  field  of  the  pop-up  menu  control  template  used  to 
create  the  control. 
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Extended  radio  button  control  record 

Figure  28-26  shows  the  format  of  the  extended  control  record  for  radio  button  controls. 
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$2E 
$38 

$3C 
$3E 


Figure  28-26    Extended  radio  button  control  record 


ct  iNext  -   Long— Handle  to  next  control;  NIL  for  last  control 


Long— Pointer  to  window  to  which  control  belongs 


ctiRect  :  Rectangle— Defines  radio  button's  boundary  rectangle 


Byte— Defines  button  visibility  and  family  affinity 
Byte— Current  type  of  highlighting 

Word-OiforT;lifon 

Long— radioControl=$84000000 

Long— Pointer  to  custom  procedure;  NIL  if  r.one 

-j  Long— Reference  to  radio  button  title  string 

Long— Reserved  for  application  use 

Long— Optional  color  table  reference;  NIL  if  none 

keyEquiv  :  Block,  $06  Bytes— Key  equivalent  record 

cti  Re  served         j  Block,  $0A  bytes— Reserved 

ctiiD  -|  Long— Application-assigned  ID 


$10 

ctlFlag 

$11 

ctlHilite 

$12 

ct lvalue 

- 

$14 

— 

ctlProc 

- 

— 

$18 

— 

ctlActlon 

- 

— 

$1C 

_ 

ctlData 

- 

— 

$20 

— 

ctlRefCon 

- 

— 

$24 

— 

ctlColor 

- 

- 

$28 

ctlVersion    — 


-      ctiMoreFiags      -|  Word— Additional  control  flags 
Word— Set  toO 
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Valid  values  for  ctiFlag  are 


ctllnvis 
Family  number 


bit  7 
bits  0-6 


Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  4-10 

Color  table  reference 

bits  2-3 

Title  reference 


bits  0-1 


l=invisible,  0=visible 

Family  numbers  define  associated  groups  of 
radio  buttons.  Radio  buttons  in  the  same  family 
are  logically  linked.  That  is,  setting  one  radio 
button  in  a  family  clears  all  other  buttons  in  the 
same  family 


Must  be  set  to  0 

Must  be  set  to  0 

Set  to  1  if  button  has  keystroke  equivalent 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  incticoior(ifitis 

not  NIL).  See  Chapter  4,  "Control  Manager,"  in 

Volume  1  of  the  Toolbox  Reference  for  the 

definition  of  the  radio  button  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  tide  reference  in  ctiData: 

00  -  tide  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  ID 
11 -invalid  value 


keyEquiv 


Keystroke  equivalent  information  stored  at  keyEquiv  is  formatted 
as  shown  in  Figure  28-2. 
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Extended  scroll  bar  control  record 

Figure  28-27  shows  the  format  of  the  extended  control  record  for  scroll  bar  controls. 
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Figure  28-27    Extended  scroll  bar  control  record 
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ct  iNext  -   Long— Handle  to  next  control;  NIL  for  last  control 


ctlOwner 


Long— Pointer  to  window  to  which  control  belongs 


ctiRect  j  Rectangle— Defines  scroll  bar's  boundary  rectangle 


ctlFlag 


ctlHilite 


ct lvalue 


ctlAction 


ctlData 


—     ctlRefCon 


Byte— Style  of  scroll  bar 

Byte— Current  type  of  highlighting 

Word— Thumb  position  between  0  and  (dataSize  —  viewSize) 


ctiProc  -|  Long— scrollControl=$86000000 

Long— Pointer  to  custom  procedure;  NIL  if  none 

Long— High-order  word=  dataSize,  low-order  word=  viewSize 

Reserved  for  application  use 

cticoior         H  Long— Optional  cola  table  reference;  NIL  if  none 


thumbRect  '■  Rectangle— Defines  thumb  rectangle 


pageRegion  j  Rectangle— Defines  page  region,  thumb  bounds 


ctiiD  -   Long— Application-assigned  ID 


ctlMoreFlags        — 


—  ctiversion 


Word— Additional  control  flags 
Word— Set  to  0 
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Valid  values  for  ctiFiag  are 

1 -invisible,  0-visible 

Must  be  set  to  0 

1-horizontal  scroll  bar,  0=vertical  scroll  bar 

1-bar  has  right  arrow,  0=bar  has  no  right  arrow 

l=bar  has  left  arrow,  0=bar  has  no  left  arrow 

1-bar  has  down  arrow,  0-bar  has  no  down  arrow 

1-bar  has  up  arrow,  0-bar  has  no  up  arrow 

Note  that  extraneous  flag  bits  are  ignored,  based  upon  the  state  of  the  horscroii  flag. 
For  example,  for  vertical  scroll  bars,  rightFlag  and  lef  tFlag  are  ignored. 


ctllnvis 

bit  7 

Reserved 

bits  5-6 

horScroll 

bit  4 

rightFlag 

bit  3 

leftFlag 

bit  2 

downFlag 

bitl 

upFlag 

bitO 

Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  4-10 

Color  table  reference 

bits  2-3 

Reserved 


bits  0-1 


Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  cticoior  (if  it  is 

not  NIL).  See  Chapter  4,  "Control  Manager,"  in 

Volume  1  of  the  Toolbox  Reference  and 

"Clarifications''  in  this  chapter  for  the 

definition  of  the  scroll  bar  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 
11 -invalid  value 
Must  be  set  to  0 
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Extended  size  box  control  record 

Figure  28-28  shows  the  format  of  the  extended  control  record  for  size  box  controls. 

■    Figure  28-28    Extended  size  box  control  record 


Long— Handle  to  next  control;  NIL  for  last  control 


$00 

_ 

_ 

- 

ctlNext 

- 

— 

— 

$04 

_ 

_ 

- 

ctlOwner 

- 

— 

— 

$08 

ctlRect 

$10 

ctlFlag 

$11 

otlHilite 

$12 

ctlValue 

- 

$14 

_ 

_ 

ctlProc 

- 

— 

$18 

_ 

ctlAction 

- 

— 

$1C 

_ 

ctlData 

- 

— 

$20 

_ 

ctlRefCon 

- 

— 

$24 

— 

ctlColor 

- 

— 

$28 

ctlReserved 

$38 

_ 

ctllD 

- 

- 

$3C 

ctlMoreFlags 

- 

$3E 

ctlVersion 

- 

Long— Pointer  to  window  to  which  control  belongs 


Byte— Define  size  box  visibility 
Byte— Current  type  of  highlighting 

Word— Not  used;  set  to  0 

Long— growControl=$88000000 

Long— Pointer  to  custom  procedure,  NIL  if  none 

Long— Not  used;  set  to  0 

Long— Reserved  for  application  use 

Long— Optional  color  table  reference;  NIL  if  none 
Block,  $10  bytes— Not  used;  set  to  0 

Long— Application-assigned  ID 

Word— Additional  control  flags 
Word— Set  toO 
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Valid  values  for  ctiFiag  are  as  follows: 


ctllnvis 

bit  7 

Reserved 

bits  1-6 

fCallWindowMgr 

bitO 

1  invisible,  0=visible 

Must  be  set  to  0 

l=call  GrowWindow  and  SizeWindow  to  track 

this  control;  0=just  highlight  control 


Valid  values  for  ctiMoreFiags  are  as  follows: 


fCtlTarget 

bit  15 

Must  be  set  to  0 

fCtlCanBeTarget 

bit  14 

Must  be  set  to  0 

fCtlWantsEvents 

bit  13 

Must  be  set  to  0 

fCtlProcNotPtr 

bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11 

Must  be  set  to  0 

Reserved 

bits  4-10 

Must  be  set  to  0 

Color  table  reference 

bits  2-3 

Defines  type  of  reference  incticoior(ifitis 
not  NIL).  See  "Error  Corrections"  in  this  chapter 
for  the  definition  of  the  size  box  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 
11 -invalid  value 

Reserved 

bits  0-1 

Must  be  set  to  0 

Chapter  28    Control  Manager  Update  28-123 


Apple  UGS  Toolbox  Reference,  Volume  3  Beta  Draft  30  August  1989 

Static  text  control  record 

Figure  28-29  shows  the  format  of  the  control  record  for  static  text  controls. 
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Figure  28-29    Static  text  control  record 


$00 


$04 


$08 


$10 
$11 


ct  iNext  -   Long— Handle  to  next  control;  NIL  for  last  control 


etiowner         -   Long— Pointer  to  window  to  which  control  belongs 


ctiRect  '■  Rectangle— Defines  text  window  boundary  rectangle 


*12  _         ctivaiue         -  Word— Text  size  field,  if  ctlData  contains  a  Pointer 
$14 


$18 

$1C 

$20 

$24 

$28 
$2A 

$38 

$3C 
$3E 


ctlFlag 


ctlHillte 


ctlAction 


ctlData 


—  ctlRefCon 


ctlJust 


Byte — Define  text  display  and  storage  attributes 
Byte— Controls  event  generation  for  control 


ctiProc  -|  Long— statTextControl=$81000000 

Long— Pointer  to  custom  procedure;  NIL  if  none 
Long— Reference  to  text  for  window 
Long— Reserved  for  application  use 


cticoior        -  Long— Not  used;  must  be  set  to  0 


Word— initial  justification  word 


ctiReserved        \  Block,  $0E  bytes— Not  used 

Long— Application-assigned  ID 


CtllD 


-       ctlMoreFlags 


—  ctlVersion  — 


Word— Additional  control  flags 
Word— Set  to  0 
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Valid  values  for  ctiFlag  are 


ctllnvis 

bit  7 

Reserved 

bits  2-6 

fSubstituteText 

bit  1 

fSubTextType 


bitO 


1  "invisible,  0=visible 

Must  be  set  to  0 

0=no  text  substitution  to  perform 

l=there  is  text  substitution  to  perform 

0=C  strings 

l=Pascal  strings 


Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  2-10 

Text  reference 

bits  0-1 

Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 
Defines  type  of  text  reference  inctiData: 

00  -  text  reference  is  pointer 

01  -  text  reference  is  handle 

10  -  text  reference  is-  resource  ID 

11  -  invalid  value 

ctiHiiite  Specifies  whether  the  control  wants  to  receive  mouse  selection 

events.  The  values  for  ctiHiiite  are  as  follows: 

0      Events  will  be  generated  when  the  mouse  button  is  pressed  in  the 

control 
255   No  events  will  be  generated  when  the  mouse  button  is  pressed  in 

the  control 

ctivalue  Contains  the  size  of  the  referenced  text  in  characters,  but  only  if  the 

text  reference  in  ctiData  is  a  pointer.  If  the  text  reference  is  either  a 
handle  or  a  resource  ID,  then  the  Control  Manager  can  extract  the 
length  from  the  handle. 
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ctUust  The  justification  word  is  passed  on  to  LETextBox2  (see 

Chapter  10,  "LineEdit  Tool  Set,"  in  Volume  1  of  the  Toolbox  Reference 
for  details  on  the  LETextBox2  tool  call),  and  is  used  to  set  the  initial 
justification  for  the  text  being  drawn.  Valid  values  for  ctUust  are 

left  Justify       0       Text  is  left  justified  in  the  display  window 
center  Justify    1        Text  is  centered  in  the  display  window 
right  Justify      -1       Text  is  right  justified  in  the  display  window 
full  Justify        2       Text  is  fully  justified  (both  left  and  right)  in 

the  display  window 

Static  text  controls  do  not  support  color  tables.  To  display  text  of  different  color,  you 
must  embed  the  appropriate  commands  into  the  text  string  you  are  displaying.  See  the 
discussion  of  LETextBox2  in  Chapter  10,  "LineEdit  Tool  Set,"  in  Volume  1  of  the  Toolbox 
Reference  for  details  on  command  format  and  syntax. 
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TextEdit  control  record 

Figure  28-30  shows  the  format  of  the  control  record  for  TextEdit  controls. 

■    Figure  28-30    TextEdit  control  record 


$00 


$04 


$08 


$10 
$11 
$12 

$14 


$18 


$1C 


$20 


$24 


$28 


$2C 


ctiNext  -   Long— Handle  to  next  control;  NIL  for  last  control 


ctlOwner 


Long— Pointer  to  window  to  which  control  belongs 


ctiReot  :  Rectangle— Defines  control  boundary  rectangle 


ctlFlag 


ctlHilite 


ct lvalue 


ctlProc 


ctlAction     — 


ctlData 


—     ctlRefCon     — 


textriags        -   Long— TextEdit  bit  flags 


textLength        -   Long— Length  of  text 


continued 


Byte— Defines  control  visibility 
Byte— Not  used;  must  be  set  to  0 

Word— Contains  the  last  reported  TextEdit  error  code 
Long— editTextCQiitrol=$85000000 


Long— Pointer  to  custom  procedure;  NIL  if  none 


Long— Pointer  to  filter  procedure 


Long— Reserved  for  application  use 


cticoior         -   Long— Reference  to  the  color  table  for  the  control 
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$30 
$38 

$3C 
$3E 
$40 

$48 

$4C 
$58 
$64 

$68 

$6C 
$6E 

$72 


continued 


biockList  *  Textlist— Cached  link  into  TextBlock  list 


ctllD 


—    ctlMoreFlags 


—    ctlVersion    — 


Long— Application-assigned  ID 

Word— Additional  control  flags 
Word— Set  to  0 


viewRect 


Rectangle— Boundary  rectangle  for  text 

totaiHeight       -   Long— Height,  in  pixels,  of  text 

linesuper  '■  SuperHandle— Cached  link  into  text  lines 

styiesuper  :  SuperHandle— Cached  link  into  style  list 

Long— Handle  to  array  of  TESty  le  records 


-  styleList 


ruler List 


UneAtEndFlag 


—      select ionStart      — 


continued 


Long— Handle  to  array  of  TERuler  records 

Word— Line  break  flag 

Long— Starting  text  offset  for  current  selection 


seiectionEnd      -  Long— Ending  text  offset  for  current  selection 
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$76 
$78 
$7A 

$7E 
$80 

$8C 

$90 
$92 

$96 

$9A 

$9E 

$0A 


—  selectionActive  — 


—   selectionState 


continued 


—     caretTlme     — 


—  nullStyleActive 


Word— Flag  indicating  whether  current  selection  is  active 
Word— State  information  about  current  selection 

Long— Blink  interval  for  caret,  in  system  ticks 

Word— Flag  indicating  whether  null  style  is  active 


nuiistyie  \  TEStyle — Null  style  definition 


—   topTextOffset   — 


—    topTextVPos 


-     vertscroiiBar     -   Long— Handle  to  vertical  scroll  bar  control  record 


Long— Offset  to  top  line  of  displayed  text 

Word— Position  of  display  window  into  text,  in  pixels 


vertScrollPos   — 


vertScrollMax 


—  vertScrollAmount 


$A4 


$A8 


horzScrollBar   — 


—   horzScrollPos 


horzScrollMax 


continued 


Long— Current  position  of  vertical  scroll  bar 

Long— Maximum  allowable  vertical  scroll 
Word— Number  of  pixels  to  scroll  on  each  click 
Long— Currently  not  supported 

Long— Currently  not  supported 

Long— Currently  not  supported 
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$AC 


—    horzScrollAmount    — 


$AE_ 

—       growBoxHandle 


$B2 

$B6 

$BA 
$BC 
$BE 

$C0 
$C4 
$C8 

$CC 

$D4 
$D6 


—    maximumLines 


—  maxCharsPerLine  — 


continued 


maximumChars         — 


raaximumHeight        — 


—        textDrawMode 


—       wordBreakHook       — 


Word— Currently  not  supported 
Long— Handle  of  size  box  control  record 

Long— Maximum  number  of  characters  allowed  in  text 

Long— Currently  not  supported 

Word— Currently  not  supported 
Word— Currently  not  supported 
Word— QuickDraw  II  drawing  mode  for  text 


Long— Pointer  to  word  break  hook  routine 
wordwrapHook      -|  Long— Pointer  to  word  wrap  hook  routine 
keyniter        -^  Long— Pointer  to  keystroke  filter  routine 


theniterRect       '■  Rectangle— Rectangle  for  generic  filter  procedure 


-   theBufferVPos   — 


theBufferHPos 


continued 


Word— Vertical  component  of  current  position 
Word— Horizontal  component  of  current  position 
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$D8 
$E6 

SEA 
$EC 
$EE 


continued 


theKeyReoord        \  KeyRecord— Parameters  for  keystroke  filter  routine 


cachedSelcOffset  — 


—   cachedSelcVPos   — 


cachedSelcHPos   — 


Long— Cached  selection  text  offset 

Word— Vertical  component  of  cached  buffer  position 
Word— Horizontal  component  of  cached  buffer  position 


mouseRect  :  Rectangle— Boundary  rectangle  for  multiclick  mouse  commands 

Long— Time  of  last  mouse  click 
Word— Kind  of  mouse  click  last  performed 
Long— Location  of  last  mouse  click 
Word— Cached  horizontal  character  position 
Long— Starting  point  of  current  selection 


$F6 

— 



- 

mouseTime 

- 

— 

$FA 

ntouseKind 

- 

$FC 

— 

_ 

lastClick 

- 

— 

$100 

savedHPos 

- 

$102 

_ 

anchorPoint 

- 

— 

Valid  values  for  ctiFlag  are 


ctllnvis 

Reserved 


bit  7 
bits  0-6 


1  "invisible,  0=visible 
Must  be  set  to  0 
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Valid  values  for  textFiags  are 

fNotControl  bit  31 

f  SingleFormat  bit  30 

f  SingleStyle  bit  29 


fNoWordWrap 


fNoScroll 


fReadOnly 


bit  28 


bit  27 


bit  26 


fSmartCutPaste 


bit  25 


fTabSwitch 


fDrawBounds 


bit  24 


bit  23 


fColorHilight 
fGrowRuler 


bit  22 
bit  21 


Must  be  set  to  0 

Must  be  set  to  1 

Indicates  the  style  options  available  to  the  user 

1  -  Allow  only  one  style  in  the  text 

0  -  Do  not  restrict  the  number  of  styles  in  the 
text 

Indicates  TextEdit  word  wrap  behavior 

1  -  Do  not  word  wrap  the  text;  only  break  lines 
on  CR  ($0D)  characters 

0  -  Perform  word  wrap  to  fit  the  ruler 
Controls  user  access  to  scrolling 

1  -  Do  not  allow  either  manual  or  auto-scrolling 

0  -  Scrolling  permitted 

Restricts  the  text  in  the  window  to  read-only 
operations  (copying  from  the  window  will  still 
be  allowed) 

1  -  No  editing  allowed 

0  -  Editing  permitted 

Controls  TextEdit  support  for  smart  cut  and 
paste  (see  Chapter  49,  "TextEdit,"  for  details 
on  smart  cut  and  paste  support) 

1  -  Use  smart  cut  and  paste 

0  -  Do  not  use  smart  cut  and  paste 
Defines  behavior  of  the  Tab  key  (see 
Chapter  49,  "TextEdit,"  for  details) 

1  -  Tab  to  next  control  in  the  window 

0  -  Tab  inserted  in  TextEdit  document 
Indicates  whether  TextEdit  will  draw  a  box 
around  the  edit  window,  just  inside  ctiRect 
(the  pen  for  this  rectangle  is  2  pixels  wide  and  1 
pixel  high) 

1  -  Draw  rectangle 

0  -  Do  not  draw  rectangle 
Must  be  set  to  0. 

Indicates  whether  TextEdit  will  resize  the  ruler 
in  response  to  the  user  resizing  the  edit  window. 
If  set  to  1,  TextEdit  will  automatically  adjust 
the  right  margin  value  for  the  ruler 

1  -  Resize  the  ruler 

0  -  Do  not  resize  the  ruler 
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fDisableSelection 


fDrawInactiveSelection 

bit  19 


Reserved 
textLength 

blockList 


bit  20  Controls  whether  user  can  select  text 

1  -  User  cannot  select  text 

0  -  User  can  select  text 

Controls  how  inactive  selected  text  is  displayed 

1  -  TextEdit  draws  a  box  around  inactive 
selections 

0  -  TextEdit  does  not  display  inactive 
selections 
bits  0-18       Must  be  set  to  0 

Number  of  bytes  of  text  in  the  record.  Your  program  must  not  modify 
this  field. 

Cached  link  into  the  linked  list  of  TextBiock  structures,  which 
contain  the  actual  text  for  the  record.  The  actual  TextList  structure 
resides  here.  Your  program  must  not  modify  this  field. 
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Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fTellAboutSize 

bit  11 

fCtllsMultiPart 

bit  10 

Reserved 

bits  4-9 

Color  table  reference 

bits  2-3 

Style  reference 


bits  0-1 


Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  1 

Must  be  set  to  1 

If  set  to  1,  a  size  box  will  be  created  in  the 

lower-right  corner  of  the  window.  Whenever  the 

control  window  is  resized,  the  edit  text  will  be 

resized  and  redrawn. 

Must  be  set  to  1 

Must  be  set  to  0 

Defines  type  of  reference  incticoior(ifitis 

not  NIL).  The  color  table  for  a  TextEdit  control 

(TECoiorTabie)  is  described  in 

Chapter  49,  TextEdit,"  later  in  this  book 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11 -invalid  value 

Defines  type  of  style  reference  in  styieRef . 

The  format  for  a  TextEdit  style  descriptor  is 

described  in  Chapter  49,  "TextEdit,"  later  in  this 

book 

00  -  style  reference  is  pointer 

01  -  style  reference  is  handle 

10  -  style  reference  is  resource  ID 
11 -invalid  value 


A  Important 


Do  not  set  f  TeliAboutsize  to  1  unless  the  control  also  has  a 
vertical  scroll  bar.  a 


viewRect  Boundary  rectangle  for  the  text,  within  the  rectangle  defined  in 

boundsRect,  which  surrounds  the  entire  record,  including  its 
associated  scroll  bars  and  oudine. 


totalHeight 
lineSuper 


Total  height  of  the  text  in  the  TextEdit  record,  in  pixels. 

Cached  link  into  the  linked  list  of  SuperBiock  structures  that  define 
the  text  lines  in  the  record. 
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styiesuper        Cached  link  into  the  linked  list  of  SuperBiock  structures  that  define 
the  styles  for  the  record. 

styieList  Handle  to  array  of  TEStyle  structures,  containing  style  information 

for  the  record.  The  array  is  terminated  with  a  long  set  to  $FFFFFFFF. 

mierList  Handle  to  array  of  TERuier  structures,  defining  the  format  rulers  for 

the  record.  Note  that  only  the  first  ruler  is  currendy  used  by  TextEdit. 
The  array  is  terminated  with  a  long  set  to  $FFFFFFFF. 

UneAtEndFiag  Indicates  whether  the  last  character  was  a  line  break.  If  so,  this  field  is 
set  to  $FFFF. 

select ionStart 

Starting  text  offset  for  the  current  selection.  Must  always  be  less  than 
selectionEnd. 

seiectionEnd    Ending  text  offset  for  the  current  selection.Must  always  be  greater 
than  selectionStart. 

selectionActive 

Indicates  whether  the  current  selection  (defined  by 
selectionStart  and  selectionEnd)  is  active: 

$0000  Active 

$FFFF  Inactive 

seiectionstate        Contains  state  information  about  the  current  selection  range: 

$0000  Off  screen 

$FFFF  On  screen 

caretTime  Blink  interrval  for  caret,  expressed  in  system  ticks. 

nullStyleActive 

Indicates  whether  the  null  style  is  active  for  the  current  selection: 

$0000  Do  not  use  null  style  when  inserting  text 

$FFFF  Use  null  style  when  inserting  text 

nuiistyle  TEStyle  structure  defining  the  null  style.  This  may  be  the  default 

style  for  newly  inserted  text,  depending  upon  the  value  of 
nullStyleActive. 

topTextof  f  set  Text  offset  into  the  record  corresponding  to  the  top  line  displayed  on 
the  screen. 
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topTextvpos      Difference.in  pixels,  between  the  topmost  vertical  scroll  position 
(corresponding  to  the  top  of  the  vertical  scroll  bar)  and  the  top  line 
currently  displayed  on  the  screen.  This  is,  essentially,  the  vertical 
position  of  the  display  window  in  the  text  for  the  record. 

vertScroiiBar  Handle  to  the  vertical  scroll  bar  control  record. 

vertscroiiPos  Current  position  of  the  vertical  scroll  bar,  in  units  defined  by 
vertScrollAmount. 


♦   Note:  that  while  TextEdit  supports  vertscroiiPos  as  a  long,  standard  Apple  IIGS 
scroll  bars  support  only  the  low-order  word.  This  leads  to  unpredictable  scroll  bar 
behavior  when  editing  large  documents. 

vertScroiiMax  Maximum  allowable  vertical  scroll,  in  units  defined  by 
vertScrollAmount. 

vertScrollAmount 

Number  of  pixels  to  scroll  on  each  vertical  arrow  click. 

horzScroiiBar  Handle  to  the  horizontal  scroll  bar  control  record.  Currently  not 
supported 

horzScroiiPos  Current  position  of  the  horizontal  scroll  bar,  in  units  defined  by 
horzScroiiAmount.  Currently  not  supported 

horzScroiiMax  Maximum  allowable  horizontal  scroll,  in  units  defined  by 
horzScroiiAmount.  Currently  not  supported 

horzScroiiAmount 

Number  of  pixels  to  scroll  on  each  horizontal  arrow  click.  Currently  not 
supported. 

growBoxHandie  Handle  of  size  box  control  record. 

maximumchars     Maximum  number  of  characters  allowed  in  the  text. 

maximumLines     Maximum  number  of  lines  allowed  in  the  text.  Currently  not  supported. 

maxCharsPerLine 

Currendy  not  supported. 

maximumHeight  Maximum  text  height,  in  pixels.  This  value  allows  applications  to  easily 
constrain  text  to  a  display  window  of  a  known  height.  Currendy  not 
supported. 
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textDrawMode    QuickDraw  II  drawing  mode  for  the  text.  See 

Chapter  16,  "QuickDraw  II,"  in  the  Toolbox  Reference  for  more 
information  on  QuickDraw  II  drawing  modes. 

wordBreakHook  Pointer  to  the  routine  that  handles  word  breaks.  See 

Chapter  49,  "TextEdit,"  for  information  about  word  break  routines. 
Your  program  may  modify  this  field. 

wordWrapHook    Pointer  to  the  routine  that  handles  word  wrap.  See 

Chapter  49,  "TextEdit,"  for  information  about  word  wrap  routines. 
Your  program  may  modify  this  field. 

keyFiiter  Pointer  to  the  keystroke  filter  routine.  See  Chapter  49,  "TextEdit," 

for  information  about  keystroke  filter  routines.  Your  program  may 
modify  this  field. 

theFiiterRect  Defines  a  rectangle  used  by  the  generic  filter  procedure  for  some  of  its 
routines.  See  Chapter  49,  "TextEdit,"  for  information  about  generic 
filter  procedures  and  their  routines.  Your  program  may  modify  this 
field. 

theBuf  f  ervpos  Vertical  component  of  the  current  position  of  the  buffer  within  the 
port  for  the  TextEdit  record,  expressed  in  the  local  coordinates 
appropriate  for  that  port.  This  value  is  used  by  some  generic  filter 
procedure  routines.  See  Chapter  49,  "TextEdit,"  for  information 
about  generic  filter  procedures  and  their  routines.  Your  program  may 
modify  this  field. 

theBuf  ferHPos  Horizontal  component  of  the  current  position  of  the  buffer  within  the 
port  for  the  TextEdit  record,  expressed  in  the  local  coordinates 
appropriate  for  that  port.  This  value  is  used  by  some  generic  filter 
procedure  routines.  See  Chapter  49,  TextEdit,"  for  information 
about  generic  filter  procedures  and  their  routines.  Your  program  may 
modify  this  field. 

theKeyRecord    Parameter  block,  in  KeyRecord  format,  for  the  keystroke  filter 
routine.  Your  program  may  modify  this  field. 

csciiGdSGlcOf  f  S©t 

Cached  selection  text  offset.  If  this  field  is  set  to  $FFFFFFFT,  then  the 
cache  is  invalid  and  will  be  recalculated  when  appropriate. 

cachedSelcVPos 

Vertical  component  of  the  cached  buffer  position,  expressed  in  local 

coordinates  for  the  output  port. 
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cachedSelcHPos 

Horizontal  component  of  the  cached  buffer  position,  expressed  in 
local  coordinates  for  the  output  port. 

mouseRect  Boundary  rectangle  for  multiclick  mouse  commands.  If  the  user  clicks 

the  mouse  more  than  once  within  the  region  defined  by  this  rectangle 
within  the  time  period  defined  for  multiclicks,  then  TextEdit 
interprets  those  clicks  as  multiclick  sequences  (double-  or  triple- 
clicks).  The  user  sets  the  time  period  with  the  Control  Panel. 

mouseTime  System  tickcount  when  the  user  last  released  the  mouse  button. 

mouseKind  Type  of  last  mouse  click: 


0 
1 
2 

lastClick 

savedHPos 


anchorPoint 


Single  click 

Double-click 

Triple-click 

Location  of  last  user  mouse  click. 

Cached  horizontal  character  position.  TextEdit  uses  this  value  to 
manage  where  it  should  display  the  caret  on  a  line  when  the  user 
presses  the  up  or  down  arrow. 

Defines  the  character  from  which  the  user  began  to  select  text  for  the 
current  selection.  When  TextEdit  expands  the  current  selection  (as  a 
result  of  user  keyboard  or  mouse  commands,  or  at  the  direction  of  a 
custom  keystroke  filter  procedure),  it  always  does  so  from  the 

anchorPoint,  not  selectionStart  or  selectionEnd. 
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Chapter  29   Desk  Manager  Update 


This  chapter  documents  new  features  of  the  Desk  Manager.  The 
complete  reference  to  the  Desk  Manager  is  in  Volume  1,  Chapter  5  of  the 
Affile  IIGS  Toolbox  Reference. 
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New  features  in  the  Desk  Manager 

It  is  now  possible  for  a  new  desk  accessory  (NDA)  to  be  a  modal  dialog  box.  When  an 
NDA  is  opened,  it  returns  a  pointer  to  its  window.  The  Desk  Manager  saves  this  pointer 
and  marks  the  NDA  open.  The  current  version  of  the  Desk  Manager  checks  the  returned 
window  pointer,  and  if  its  value  is  0  (if  it  is  a  null  pointer)  then  the  Desk  Manager  does  not 
mark  the  NDA  open.  Subsequent  attempts  to  open  the  NDA  simply  select  the  open 
window  until  the  NDA  is  closed.  A  programmer  can  therefore  write  an  NDA  that  opens  a 
modal  dialog  box  when  chosen.  When  the  dialog  box  is  dismissed,  the  NDA  can  be  chosen 
again  without  having  been  explicidy  closed. 


Scrollable  CDA  menu 

The  classic  desk  accessory  (CDA)  menu  is  now  scrollable.  Previously,  the  menu  held  a 
maximum  of  13  entries  in  a  fixed  display.  Now,  up  to  249  desk  accessories  can  be  installed 
and  displayed. 

Scrolling  takes  place  only  on  systems  with  14  or  more  CDAs  installed.  When  the  menu  is 
scrollable,  the  system  displays  a  more  message  at  each  scrollable  end  of  the  menu.  That  is, 
if  there  are  additional  items  above  those  currently  visible,  the  more  message  appears  at 
the  top  of  the  menu.  Similarly,  if  there  are  more  items  below  those  currendy  visible,  a  more 
message  appears  at  the  bottom  of  the  menu.  Messages  may  be  placed  at  both  the  top  and 
bottom  of  the  menu,  if  appropriate. 

The  new  menu  behaves  somewhat  differendy  from  the  old  one.  When  the  user  returns  to 
the  CDA  menu  from  an  accessory,  the  name  of  that  accessory  is  highlighted  (previously, 
the  Control  Panel  entry  was  highlighted).  In  addition,  the  user  can  no  longer  wrap  from  the 
bottom  of  the  menu  to  the  top,  or  vice  versa. 
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The  valid  keystrokes  for  the  CDA  menu  are: 


Keystroke 


Effect 


Up  Arrow 

Command-Up  Arrow 

Down  Arrow 

Command-Down  Arrow 

Enter  or  Return 
Esc 


Moves  selection  box  up  one  entry  in  the  menu;  no  effect  if  at 
the  top  of  the  menu 

Moves  selection  box  up  one  page  in  the  menu;  no  effect  if  at 
the  top  of  the  menu 

Moves  selection  box  down  one  entry  in  the  menu;  no  effect  if 
at  the  bottom  of  the  menu 

Moves  selection  box  down  one  page  in  the  menu;  no  effect  if 
at  the  bottom  of  the  menu 

Selects  the  highlighted  item 

Selects  Quit 


Run  queue 

The  run  queue  allows  you  to  install  tasks  (run  items)  that  need  to  be  called  periodically. 
You  establish  the  periodicity  of  the  call  by  managing  a  field  in  the  run  item  header.  The 
Desk  Manager  has  two  new  system  calls,  AddToRunQ  and  RemoveFromRunQ,  that  allow 
you  to  install  and  remove  run  items  from  the  queue. 

The  system  examines  the  run  queue  at  system  task  time,  when  the  system  is  guaranteed  to 
be  free  and  all  tools  are  available.  For  each  run  item  in  the  queue,  the  system  adjusts  the 
period  header  field.  If  the  specified  time  period  has  elapsed,  the  system  then  calls  the 
run  item. 

The  run  queue  is  quite  similar  to  the  heartbeat  queue,  and  should  be  used  in  its  place. 
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Each  run  item  must  be  preceded  by  a  header  formatted  as  follows: 


$00 

$04 
$06 
$08 


Reserved 


period 


—  signature 


Reserved 


Long— Used  by  system  as  link  to  next  run  queue  item 

Wad  (unsigned)— Period  to  wait,  in  ticks 

Word— Header  signature,  to  ensure  integrity— set  to  $A55A 

Long— Used  by  system  to  know  when  item  was  last  executed 


period 


Specifies  the  minimum  number  of  system  ticks  that  are  to  elapse 
between  run  item  executions.  Each  system  tick  represents  l/60th  of  a 
second.  A  value  of  0  indicates  that  the  item  is  to  be  called  as  often  as 
possible.  A  value  of  $FFFF  indicates  that  the  item  should  never  be 
called.  While  the  run  queue  supports  call  frequencies  up  to 
approximately  60  per  second,  the  timing  is  less  accurate  for  periods 
shorter  than  one  second. 


A  Important 


Run  item  code  must  reset  the  period  field  before  returning  control  to 
the  system.  Failure  to  do  so  will  result  in  a  period  of  0,  which  will 
cause  the  item  to  be  called  constandy.  a 


signature  Used  by  the  system  to  ensure  that  the  header  is  well  formed.  The  value 

of  this  field  must  be  $A55A. 

The  entry  point  must  immediately  follow  the  header.  Run  items  need  not  check  the  busy 
flag,  since  the  system  is  guaranteed  to  be  free  before  any  run  item  is  invoked.  However, 
run  items  must  be  careful  to  save  and  restore  the  operating  environment,  since  they  may 
be  invoked  from  TaskMaster,  as  well  as  from  an  application.  You  should  also  be  careful  to 
either  unload  your  run  items  at  application  termination,  or  ensure  that  remaining  items  are 
not  purgeable. 

While  the  run  queue  and  heartbeat  queue  (see  Chapter  14,  "Miscellaneous  Tool  Set,"  in 
Volume  1  of  the  Toolbox  Reference  for  information  about  the  heartbeat  queue)  are 
somewhat  similar,  there  are  some  significant  differences.  First,  the  run  item  header  has  an 
additional  field  (the  second  Reserved  field).  Second,  the  system  does  not  remove  items 
from  the  run  queue  when  their  pe  r i  od  reaches  0. 
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Run  queue  example 

Following  is  an  example  run  item,  which  beeps  the  speaker  every  15  minutes. 

RunQ  example  task  that  beeps  every  15  minutes. 

It  is  provided  in  MPWIIgs  assembler  format.  The  first  portion  is  the 

task  header. 

BeepHdr     Record 

ds.L  1  ;  reserve  1  long  for  link  to  next  runQ  entry 

period      dc.W  $D2F0  ;  number  of  60th  of  a  sec  (54000=15  minutes) 

dc.W  $A55A  ;  signature  used  to  test  for  queue  integrity 

dc.L  0  ;  used  by  desk  mgr  to  keep  track  of  the  time 

EndR 

Now  the  actual   code   of  the  task  goes   here. 

BeepTask  Proc 

with  BeepHdr 

_SysBeep  ;    beep  the  speaker  once 

Ida   #$D2F0  ;    and  now   recharge  the  period  for  next    call 

sta   >period  ;    NOTE: Use  long  addressing:    DataBank  unknown 

rtl  ;    and  to  exit  use  an  RTL 
EndP 

The  following  code  installs  the  above  item  into  the  run  queue 
PushLong  #BeepHdr 
ldx  #$1F05 
jsl   >$E10000 
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New  Desk  Manager  calls 

The  following  new  Desk  Manager  calls  support  the  run  queue  and  desk  accessory  removal. 

AddToRunQ     $1F05 

Adds  the  specified  routine  to  the  head  of  the  run  queue. 

Parameters 

Stack  before  call 


Previous  contents 

runltemPtr     - 

Long— Pointer  to  run  item  to  add 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C                               extern  pascal  void  AddToRunQ (runltemPtr) ; 

Poin 

ter        runltemPtr; 
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RemoveFromRunQ     $2005 

Removes  the  specified  run  item  from  the  run  queue. 

Parameters 

Stack  before  call 


Previous  contents 

-     runltemPtr    - 

Long— Pointer  to  run  item  to  remove 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C                               extern  pascal  void  RemoveFromRunQ (runltemPtr) ; 

Poin 

ter        runltemPtr; 
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RemoveCDA    $2105 

Removes  the  specified  CDA  from  the  Desk  Manager  CDA  list.  This  routine  does  not 
dispose  of  the  memory  used  by  the  DA. 

This  routine  is  the  complement  of  instaiiCDA  (which  is  described  in 
Chapter  5,  "Desk  Manager,"  in  the  Toolbox  Reference). 

You  should  be  very  careful  before  issuing  this  call.  Users  generally  install  desk  accessories 
for  their  own  use;  you  should  not  spontaneously  remove  them  from  the  system.  Also,  note 
that  many  desk  accessories  install  other  custom  code  (in  the  run  queue,  for  example);  you 
should  not  remove  them  unless  you  know  that  the  other  code  has  been  removed,  as  well. 

Parameters 

Stack  before  call 


Previous  contents 


idHandle 


Stack  after  call 


Long— Handle  to  CDA  header 
<— SP 


Previous  contents 


Errors 


$0510 


<— SP 

DaNotFound 


Specified  desk  accessory  not 
found. 


extern  pascal  void  RemoveCDA ( idHandle ) ; 
Handle    idHandle; 
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RemoveNDA    $2205 

Removes  the  specified  NDA  from  the  Desk  Manager  NDA  list.  This  routine  does  not 
dispose  of  the  memory  used  by  the  DA. 

This  routine  is  the  complement  of  instaiiNDA  (which  is  described  in 
Chapter  5,  "Desk  Manager,"  in  the  Toolbox  Reference). 

This  call  does  not  rebuild  the  Apple  menu.  Your  application  must  rebuild  the  menu  by 
issuing  the  FixAppleMenu  tool  call. 

Parameters 

Stack  before  call 


Previous  contents 


idHandle 


Stack  after  call 


Long— Handle  to  NDA  header 
<— SP 


Previous  contents 


Errors 


$0510 


<— SP 

DaNotFound 


Specified  desk  accessory  not 
found. 


extern  pascal  void  RemoveNDA ( idHandle ) ; 
Handle    idHandle; 
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Chapter  30   Dialog  Manager  Update 


This  chapter  documents  new  features  of  the  Dialog  Manager.  The 
complete  reference  to  the  Dialog  Manager  is  in  Volume  1,  Chapter  6  of 
the  Apple  IIGS  Toolbox  Reference. 


30-1 


Apple  11GS  Toolbox  Reference,  Volume  3  Beta  Draft  30  August  1989 


Error  corrections 

This  section  explains  changes  that  have  been  made  to  the  Dialog  Manager's 
documentation  in  the  Apple  IIGS  Toolbox  Reference. 

m   The  documentation  for  setDitemType  on  page  6-82  of  the  Toolbox  Reference  says 
that  the  call  is  used  to  change  a  dialog  item  to  a  different  type.  In  fact, 
SetDitemType  should  be  used  only  to  change  the  state  of  an  item  from  enabled  to 
disabled  or  vice  versa. 

The  Dialog  Manager  does  not  support  dialog  item  type  values  of  picitem  or 
icomtem,  contrary  to  what  the  Toolbox  Reference  states  in  Table  6-3  on  page  6-12. 
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Chapter  31   Event  Manager  Update 


This  chapter  documents  new  features  of  the  Event  Manager.  The 
complete  reference  to  the  Event  Manager  is  in  Volume  1,  Chapter  7  of  the 
Apple  UGS  Toolbox  Reference. 
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New  features  in  Event  Manager 

The  following  sections  discuss  new  features  of  the  Event  Manager. 


Journaling  changes 

Previously,  journaling  did  not  capture  operations  that  involved  the  ReadMouse 
Miscellaneous  Tool  Set  call,  because  that  call  did  not  support  journaling.  As  discussed  in 
Chapter  39,  "Miscellaneous  Tool  Set  Update,"  in  this  book,  ReadMouse  has  been  changed 
to  support  journaling.  As  a  result,  journaling  routines  must  now  handle  a  new  journal  code. 

When  an  application  calls  ReadMouse,  and  journaling  is  on,  your  journaling  routine  will  be 
called  with  a  journal  code  of  6  and  resultPtrm)!  point  to  a  6-byte  record  containing 
ReadMouse  data.  This  record  has  the  following  format: 


$00 
$02 
$04 


statusMode 


yLo cation 


xLo cation 


Word— Mouse  status/mode  bytes 

Word— Absolute  y  location  of  pointing  device 

Word— Absolute  x  location  of  pointing  device 


statusMode        Mouse  status  and  mode  bytes,  as  described  on  pages  14-35  and  14-36 
of  the  Toolbox  Reference. 


31-2      Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  11GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Keyboard  input  changes 

The  system  now  processes  keyboard  input  through  a  translation  routine,  allowing  Apple 
IIGS  and  Macintosh®  keystrokes  to  match.  The  translation  routine  uses  a  resource-based 
keystroke  translation  table,  which  is  identified  by  a  unique  resource  ID.  You  can  assign 
other  tables  to  suit  the  needs  of  a  particular  language  or  keyboard.  There  are  new  Event 
Manager  calls  to  read  or  write  the  current  keyboard  translation  table  resource  ID. 

Note  that  the  system  translates  keystrokes  before  performing  dead  key  replacements.  To 
modify  dead-key  sequences  you  may  find  it  easier  to  modify  the  appropriate 
transTabie  entry,  since  that  table  is  more  straightforward  than  the  deadKeyTabie 
and  replacementTable. 

The  keystroke  translation  table  must  be  formatted  as  follows: 


$000 


$100 


transTabie  \  256  Bytes— Keystroke  translation  array 


deadKeyTabie        '■  xx  Bytes— Dead-key  validation  array 


$100+xx 


:     replacementTable     j  yy  Bytes— Dead-key  replacement  array 


transTabie        This  is  a  packed  array  of  bytes  used  to  map  the  ASCII  codes  produced 
by  the  keyboard  into  the  character  value  to  be  generated.  Each  cell  in 
the  array  direcdy  corresponds  to  the  ASCII  code  that  is  equivalent  to 
the  cell  offset.  For  example,  the  transTabie  cell  at  offset  $0D  (13 
decimal)  contains  the  character  replacement  value  for  keyboard  code 
$0D,  which,  for  a  straight  ASCII  translation  table,  is  a  Return  character 
(CR).  The  transTabie  cells  from  128  to  255  ($80  to  $FF)  contain 
values  for  Option-key  sequences  (such  as  Option-S). 
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deadKeyTable 


This  table  contains  entries  used  to  validate  dead  keys.  Dead  key 
refers  to  keystrokes  used  to  introduce  multikey  sequences  that  result 
in  single  characters.  For  example,  pressing  Option-u  followed  by  e 
yields  an  e  with  an  umlaut.  There  is  one  entry  in  deadKeyTable  for 
each  defined  dead  key.  The  last  entry.must  be  set  to  $0000.  Each  entry 
must  be  formatted  as  follows: 


deadKey 


offset 


Byte— Character  code  for  dead  key 

Byte— Offset  from  deadKeyTable  into  replacementTable 


deadKey  Contains  the  character  code  for  the  dead  key.  The  system  uses 

this  value  to  check  for  user  input  of  a  dead  key.  The  system 
compares  this  value  with  the  first  user  keystroke. 

offset  Byte  offset  from  beginning  of  deadKeyTable  into  relevant 

subarray  in  replacementTable,  divided  by  2.  The  system 
uses  this  value  to  access  the  valid  replacement  values  for  the 
dead  key  in  question. 

replacementTable 

This  table  contains  the  valid  replacement  values  for  each  dead  key 
combination.  This  table  is  made  up  of  a  series  of  variable-length 
subarrays,  each  relevant  to  a  particular  dead  key.  The  last  entry  in  each 
sub-array  must  be  set  to  $0000.  Each  entry  in  the 
replacementTable  must  be  formatted  as  follows: 


scanKey 


replaceValue 


Byte— Character  code  for  dead  key  combination 
Byte— Result  character  code  for  dead  key  combination 


scanKey 


replaceValue 


Contains  a  valid  character  code  for  dead  key  replacement.  The 
system  uses  this  field  to  determine  whether  the  user  entered  a 
valid  dead  key  combination.  The  system  compares  this  value 
with  the  second  user  keystroke. 

Contains  the  replacement  value  for  the  character  specified  in 
scanKey  for  this  entry.  The  system  delivers  this  value  as  the 
replacement  for  a  valid  dead  key  combination. 
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New  Event  Manager  calls 

There  are  several  new  Event  Manager  calls,  many  concerning  the  new  keyboard  translation 
feature. 


GetKeyTranslation     $1B06 

Returns  the  identifier  for  the  currently  selected  keystroke  translation  table.  Before  setting 
a  new  translation  table,  your  application  should  read  and  save  the  current  identifier.  When 
your  application  terminates,  it  should  restore  the  previous  keystroke  translation  table. 
Use  the  setKeyTransiation  call  to  modify  the  current  identifier. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


kTransID 


Errors 
C 


None 


Word— Keyboard  translation  identifier  ($0000  to  $00FF) 
<— SP 


extern  pascal  Word  GetKeyTranslation () ; 
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SetAutoKeyLimit     $1A06 

Controls  how  repeated  keystrokes  are  inserted  into  the  event  queue.  The  default  value  for 
the  limit  is  0,  which  specifies  that  auto-key  events  are  inserted  only  if  no  other  events  are 
already  in  the  queue.  The  newLimit  parameter  determines  how  many  auto-key  events  must 
be  in  the  event  queue  before  Post  Event  ceases  to  add  them.  For  example,  if  newLimit  is 
0,  then  the  default  condition  is  maintained:  PostEvent  will  not  add  auto-key  events 
unless  the  queue  is  empty.  However,  if  newLimit  is  5,  then  PostEvent  will  add  five  auto- 
key  events  to  the  queue  before  it  reverts  to  the  rule  that  no  more  auto-key  events  are  to 
be  posted. 


Stack  before  call 

Previous  contents 

newLimit 

Word— Limit  for  inserted  auto-key  events 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                 None 

C                            exte 

rn  pascal  void  SetAutoKey Limit (newLimit) ; 

Word 

newLimit ; 
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SetKeyTranslation     $1C06 

Sets  a  new  keystroke  translation  table.  Once  set,  the  selected  keystroke  translation  table 
stays  in  effect  until  this  call  is  issued  again,  irrespective  of  application  termination, 
system  resets,  or  system  power  off.  Before  setting  a  new  value  for  the  keystroke 
translation  table,  your  application  should  read  and  save  the  current  value,  using  the 
GetKeyTransiation  tool  call.  Your  application  should  then  restore  that  previous  value 
when  it  is  finished. 

The  system  reads  keystroke  translation  tables  from  resources  of  type  $8021  and  ID 
$0FFF06xx,  where  xx  derives  from  the  low-order  byte  of  the  kTransID  parameter. 

This  call  uses  the  current  resource  search  path  to  find  the  specified  resource.  If  you  want 
your  translation  to  stay  in  effect  after  your  application  has  terminated,  you  must  place 
the  translation  table  resource  in  the  system  resource  file. 

If  the  system  cannot  find  a  resource  corresponding  to  the  value  specified  in  kTransID,  the 
keyboard  defaults  to  the  standard  keystroke  translation  table  ($00FF). 


Stac 

k  before  call 

Previous  contents 

kTransID 

Word— Keystroke  translation  table  identifier  (low-o 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

c 

exte 

rn 

pascal  void  SetKeyTranslation (kTransID) ; 

kTransID 


Word      kTransID; 

The  following  are  standard  values  for  kTransID. 

$0000      Use  old-style  Apple  IIGS  keyboard  mapping 
$00FF      Use  standard  keyboard  remapping  (makes  Apple  IIGS  key 
sequences  match  Macintosh) 
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Chapter  32   Font  Manager  Update 


This  chapter  documents  new  features  of  the  Font  Manager.  The  complete 
reference  to  the  Font  Manager  is  in  Volume  1,  Chapter  8  of  the 
Apple  BGS  Toolbox  Reference. 
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New  features  in  the  Font  Manager 

■  The  current  version  of  the  Font  Manager  incorporates  several  changes.  In  previous 
versions,  FMStartup  opened  each  font  file  in  the  FONTS  folder,  and  constructed  lists 
of  information  for  all  available  fonts.  These  lists  contained  font  IDs,  font  names,  and 
so  forth  for  every  font  in  the  FONTS  folder.  The  present  version  of  the  Font  Manager 
does  this  same  work  the  first  time  it  starts  up,  but  caches  all  the  information  it 
compiles  in  a  file  called  FONT.LISTS  in  the  FONTS  folder. 

The  next  time  the  Font  Manager  starts  up,  it  checks  all  the  creation  and  modification 
dates  and  times  in  font  files  against  the  information  in  FONT.LISTS.  It  compiles  new 
FONT.LISTS  information  only  if  it  finds  new  font  files  or  other  evidence  of  change. 
Otherwise,  it  simply  starts  up  with  the  information  stored  in  the  FONT.LISTS  file.  In 
most  cases,  because  it  doesn't  have  to  open  every  font  file,  the  Font  Manager  can  start 
up  much  more  quickly. 

■  A  bug  has  been  fixed  in  the  chooseFont  call.  Previously,  ChooseFont  would  hang 
the  system  if  any  update  events  were  pending  when  the  call  was  made.  Now, 
ChooseFont  will  not  hang  the  system  under  these  circumstances;  the  system  leaves 
update  events  in  the  Event  Queue  for  processing  by  the  application. 

■  In  addition,  the  ChooseFont  dialog  now  uses  Newwindow2,  with  a  control  template 
that  can  be  kept  in  a  resource  file.  As  a  result,  this  dialog  can  be  internationalized  more 
easily. 

■  Scaled  fonts  may  now  contain  more  than  65,535  bytes  of  data.  See 

Chapter  43,  "QuickDraw  II  Update,"  later  in  this  book  for  the  layout  of  the  new  font 
record. 

■  A  bug  that  corrupted  the  font  family  list  has  been  fixed.  This  bug  had  varied 
symptoms,  including  incorrect  font  name  displays  in  the  Choose  Font  dialog  and  in  the 
Font  menu,  and  Font  Manager  crashes,  among  others. 
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New  call 

The  new  call  instaiiwithstats  is  provided  to  simplify  the  process  of  installing  fonts.  It  allows  an 
application  to  preserve  certain  information  that  is  normally  lost  during  font  installation. 


InstallWithStats     $1C1B 

Installs  a  font  and  returns  information  about  that  font.  When  an  application  requests  the 
installation  of  a  font,  the  Font  Manager  attempts  to  install  the  requested  font,  but  it  may 
not  be  available.  In  such  cases,  the  Font  Manager  will  install  the  closest  match  it  can  find 
to  the  requested  font. 

instaiiwithstats  installs  a  font  just  as  if  the  application  had  called  instaiiFont, 
but  it  returns  a  FontstatRec  in  the  buffer  pointed  to  by  resultPtr.  This  record  contains 
the  ID  of  the  installed  font,  which  may  be  different  from  the  font  requested.  It  also 
contains  the  purge  status  that  the  font  had  before  it  was  installed.  Since  purge  status  can 
be  changed  by  installation,  this  information  can  make  it  easier  to  restore  a  font's  purge 
status.  If  you  need  to  know  an  installed  fonfs  purge  status,  use  FindFontstats. 

Parameters 

Stack  before  call 


Previous  contents 


desiredID 


scaleWord 


resultPtr 


Long— Font  ID  of  desired  font 

Word— Desired  font  size 

Long— Pointer  to  buffer  to  receive  RontstatRec 

<— SP 


Stack  after  call 


Previous  contents 


Errors 


None 


<— SP 
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extern  pascal  void  InstallWithStats (desiredID, 
scaleWord,  resultPtr) ; 


resultPtr 


Long 
Word 
Pointer 


desiredID; 
scaleWord; 
resultPtr; 


On  return  from  instaiiwithstats,  the  buffer  pointed  to  by 
resultPtr  will  contain  a  FontstatRec  formatted  as  follows 


-   Long— Font  ID  record 


Word— FontstatBit  s  defining  font  status 
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Chapter  33   Integer  Math  Tool  Set  Update 


This  chapter  documents  changes  to  the  Integer  Math  Tool  Set.  The 
complete  reference  to  Integer  Math  is  in  Volume  1,  Chapter  9  of  the 
Apple  IIGS  Toolbox  Reference. 
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Clarifications 

The  Long2Dec  Integer  Math  tool  call  now  correctly  handles  input  long  values  that  have 
the  low-order  three  bytes  set  to  zero.  Previously,  if  the  input  long  had  its  low-order 
three  bytes  set  to  zero,  Long2Dec  would  always  return  a  zero  value,  even  if  the  high- 
order  byte  was  non-zero. 
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Chapter  34   LineEdit  Tool  Set  Update 


This  chapter  documents  new  features  of  the  LineEdit  Tool  Set.  The 
complete  reference  to  LineEdit  is  in  Volume  1,  Chapter  10  of  the 
Apple  IIGS  Toolbox  Reference. 
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New  features  in  LineEdit 

■   LineEdit  now  supports  password  fields.  Password  fields  do  not  echo  user  input  as 
typed.  Instead,  each  input  character  is  echoed  with  a  special  character.  Your 
application  can  set  the  echo  character;  the  default  is  asterisk  (*). 

The  LineEdit  edit  record  has  a  new  field,  lepwchar,  that  supports  the  password 
feature.  This  field  defines  the  screen  echo  character  for  password  fields.  It  is  located 
at  the  end  of  the  edit  record.  The  LineEdit  record  is  now  formatted  as  shown  in  Figure 
34-1. 

To  indicate  that  a  LineEdit  field  is  a  password  field,  set  the  high-order  bit  of  the 
maxSize  field  in  the  LineEdit  control  template  to  1  (see  "LineEdit  control  template"  in 
Chapter  28,  "Control  Manager  Update,"  earlier  in  this  book  for  more  information). 

Figure  34-1  shows  the  layout  of  the  new  LineEdit  record. 
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Figure  34-1      LineEdit  Edit  record  (new  layout) 


$00 

$04 
$06 
$08 

$10 
$18 

$1C 
$1E 
$20 
$22 
$24 
$26 
$28 
$2A 

$2E 

$32 

$36 


—    leLineHandle    — 


-     leLineHite 


—     leBaseHite 


—     leSelStart 


$38  _ 


leLengtb 


—    leMaxLength    — 


lePort 


leSelEnd 


leActFlg 


leCarAct 


leCarOn 


Long— Handle  to  text 

Word— Integer;  current  text  length 
Word— Integer;  maximum  text  length 


leDestRect  \  Rectangle— Destination  rectangle 

leviewRect  \  Rectangle— View  rectangle 


leJust 


lePWChar 


-  Long— Pointer  to  GrafPort 


-  Word— Reserved  for  internal  use 


—     leCarTime     — 


-   leHlliteHook   - 


leCaretHook    — 


Word— Integer;  used  for  highlighting 
Word— Integer;  used  for  drawing  text 
Word— Integer;  used  for  start  of  selection  range 
Word— Integer;  used  for  end  of  selection  range 
Word— Reserved  for  internal  use 


H  Word— Reserved  for  internal  use 
Long— Reserved  for  internal  use 


Long— Pointer  to  highlight  routine 

Long— Pointer  to  caret  routine 

Word— Justification  control  word 

Word— Password  field  screen  echo  character 
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leMaxLength      Indicates  the  maximum  text  length  allowed  in  the  LineEdit  field.  Valid 
values  range  from  1  to  255.  The  high-order  bit  governs  whether  the 
field  is  a  password  field.  If  the  bit  is  set  to  1,  then  the  field  is  a 
password  field,  and  user  input  is  echoed  with  character  values 
specified  by  the  contents  of  the  lepwchar  field. 

lepwchar  Defines  the  character  to  be  echoed  in  password  fields.  This  field 

contains  the  ASCII  code  for  the  echo  character  in  its  low-order  byte. 
Default  system  value  is  asterisk  (*). 
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New  call 

This  new  LineEdit  tool  call  returns  the  address  of  the  current  LineEdit  control  definition 
procedure. 


GetLEDefProc     $24l4 

Returns  the  address  of  the  current  LineEdit  control  definition  procedure.  The  system 
issues  this  call  when  the  Control  Manager  starts  up  in  order  to  obtain  the  address  of  the 
LineEdit  control  definition  procedure.  This  call  is  not  intended  for  application  use. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


-     defProcPtr     - 


Errors 
C 


None 


Long— Pointer  to  LineEdit  control  definition  procedure 
<— SP 


extern  pascal  Pointer  GetLEDefProc  () ; 
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Chapter  35   List  Manager  Update 


This  chapter  documents  new  features  of  the  List  Manager.  The  complete 
reference  to  the  List  Manager  is  in  Volume  1,  Chapter  11  of  the 
Apple  IIGS  Toolbox  Reference. 
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Clarifications 

■  The  Apple  UGS  Toolbox  Reference  states  that  a  disabled  item  of  a  list  cannot  be 
selected.  In  fact,  a  disabled  item  can  be  selected,  but  it  cannot  be  highlighted.  The 
List  Manager  provides  the  ability  to  select  disabled  (dimmed)  items  so  that  it  is 
possible,  for  instance,  for  a  user  to  select  a  disabled  menu  choice  as  part  of  a  help 
dialog.  To  make  an  item  unselectable,  set  it  inactive  (see  "List  Manager  definitions" 
later  in  this  chapter). 

■  Any  List  Manager  tool  call  that  draws  will  change  fields  in  the  GrafPort  If  you  are  using 
List  Manager  tool  calls  you  must  set  up  the  GrafPort  correctly  and  save  any  valuable 
GrafPort  data  before  issuing  the  call. 

■  Member  text  is  now  drawn  in  16  colors  in  both  320  and  640  mode. 

■  Previous  versions  of  List  Manager  documentation  do  not  clearly  define  the  relationship 
between  the  listview,  listMemHeight,  and  listRect  fields  in  the  list  record. 
To  clarify  this  point,  note  that  the  following  formula  must  be  true  for  values  in  any  list 
record: 

(listview  'listMemHeight)  +  2  -  listRect.v2  -  listRect.vl 

If  you  set  listview  to  0,  the  List  Manager  will  automatically  adjust  the 
iistRect.v2  field  and  set  the  listview  field  so  that  this  formula -holds.  Note  that 
if  you  pass  a  0  value  for  listview  the  bottom  boundary  of  listRect  may  change 
slighdy. 


List  Manager  definitions 

The  following  terms  define  the  valid  states  for  a  list  item. 

inactive  Bit  5  of  the  list  item's  memFlag  field  is  set  to  1.  Inactive  items  appear 

dimmed  and  cannot  be  highlighted  or  selected. 

disabled  Bit  6  of  the  list  item's  memFlag  field  is  set  to  1.  Disabled  items  appear 

dimmed  and  cannot  be  highlighted. 

enabled  Bit  6  of  the  list  item's  memFlag  field  is  set  to  0.  Enabled  items  appear 

normal  and  can  be  highlighted. 

selected  Bit  7  of  the  list  item's  memFlag  field  is  set  to  1.  This  bit  is  set  when  a 

user  clicks  on  the  list  item,  or  the  item  is  within  a  range  of  selected  items. 
A  selected  item  appears  highlighted  only  if  it  is  also  enabled. 
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highlighted  A  member  of  a  list  appears  highlighted  only  when  it  is  both  selected  and 

enabled.  This  means  that  bit  7  of  the  memFlag  field  is  set  to  1  and  bit  6 
is  set  to  0.  A  highlighted  member  is  drawn  in  the  highlight  colors. 
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New  features  in  the  List  Manager 

■   The  latest  revision  of  the  List  Manager  includes  new  versions  of  the  tool  calls  that 
provide  more  flexible  interfaces  for  application  programmers  in  two  ways.  First,  these 
new  List  Manager  routines  allow  your  application  to  pass  an  item  number,  rather  than  a 
list  record  pointer,  to  identify  an  item  to  process.  This  frees  you  from  tracking  pointer 
values,  and  allows  you  to  focus  on  the  more  useful  item  number.  Second,  your 
application  need  no  longer  maintain  the  list  record.  All  new  tool  calls  allow  you  to 
identify  the  list  by  a  handle  to  the  list  control  record.  List  Manager  returns  this  handle 
atCreateList  or,  preferably,  NewControi2  time. 

The  list  Type  field  now  supports  a  flag  that  governs  where  the  scroll  bar  is  to  be 
created.  Bit  2  of  list  Type  determines  whether  the  scroll  bar  is  created  inside  or 
outside  of  listRect.  If  the  bit  is  set  to  1,  the  List  Manager  adjusts  the  right  side  of 
listRect  to  accommodate  the  scroll  bar,  creates  the  scroll  bar  inside  of  the  adjusted 
listRect,  and  then  sets  the  flag  to  0.  If  the  bit  is  set  to  0,  the  scroll  bar  resides 
outside  listRect.  This  works  the  same  way  with  old-style  control  records. 

A  Important      When  using  resources  with  the  List  Manager,  be  careful  to  define  the 
memory  referenced  by  listRef  (see  "NewList2"  later  in  this  chapter) 
as  unpurgeable  if  you  plan  to  use  the  sortList  call.  Otherwise,  in 
response  to  a  memory  allocation  request,  the  sorted  list  may  be 
purged  from  memory.  Then,  when  your  application  next  issues  a  List 
Manager  call,  the  system  will  reload  the  unsorted  list,  a 
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New  List  Manager  calls 

The  following  new  List  Manager  calls  support  a  new,  more  flexible  programming  interface. 
In  general,  these  calls  provide  the  same  functionality  as  the  old  versions. 


DrawMember2     $111C 

Draws  one  or  all  members  of  a  specified  list.  If  your  application  goes  directly  to  the 
member  record  to  change  the  state  of  a  member,  the  application  should  then  call 
DrawMember  orDrawMember2.  Unlike  DrawMember,  this  call  accepts  an  item  number 
specification  for  the  member  to  draw.  Passing  an  item  number  of  0  causes  the  List 
Manager  to  redraw  the  entire  list. 

Parameters 

Stack  before  call 


Previous  contents 


itemNum 


ctlHandle      - 


Stack  after  call 


Word — Item  number  to  redraw 
Long— Handle  of  the  list  control 
<— SP 


Previous  contents 


<— SP 


Errors 
C 


None 


extern  pascal  void  DrawMember2 (itemNum,  ctlHandle) 


Word      itemNum; 
Handle    ctlHandle; 
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NewList2     $161C 

Resets  the  list  control  according  to  a  specified  list  record.  Your  application  passes  the 
parameters  controlling  the  creation  of  the  list  on  the  stack,  rather  than  in  a  list  record  (as 

with  NewList). 

Parameters 

Stack  before  call 


Previous  contents 


drawPtr 


listStart 


UstRef 


listRepesc 


HstSize 


ctlHandle 


Stack  after  call 


Long— Pointer  to  member  draw  routine;  NIL  for  default  routine 

Word— Item  number  of  first  displayed  list  member 

Long— Reference  to  list 

Word— Descriptor  for  listRef 
Word— Number  of  items  in  the  list 

Long— Handle  of  the  list  control  returned  by  NewControi2 

<— SP 


Previous  contents 


Errors 
C 


drawPtr 


None 


<— SP 


extern  pascal  void  NewList2 (drawPtr,  listStart, 
listRef,  listRefDesc,  listSize, 
ctlHandle) ; 

Pointer  drawPtr; 

Word  listStart,  listRefDesc,  listSize; 

Long  listRef; 

Handle  ctlHandle; 

Pointer  to  custom  list  member  drawing  routine.  NIL  value  causes  the 
List  Manager  to  use  its  standard  routine. 
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HstStart  Item  number  of  first  list  item  to  display.  A  value  of  $FFFF  tells  the  List 

Manager  to  use  the  value  currently  stored  in  the  list  control  record. 
Never  set  this  parameter  to  0. 

UstRef  Reference  (pointer,  handle,  or  resource  ID)  to  the  list.  The  value  of 

listRefDesc  governs  how  the  List  Manager  interprets  this  field.  A  value 
of  $FFFFFFFF  tells  the  List  Manager  to  use  the  value  currently  stored  in 
the  list  control  record. 

listRefDesc  Defines  the  type  of  reference  stored  in  UstRef. 

0  UstRef  reference  is  a  pointer 

1  /is/preference  is  a  handle 

2  UstRef  'reference  is  a  resource  ID 
$FFFF  no  change 


♦   Note:  If  you  set  either  UstRef  or  listRefDesc  to  -1,  then  you  must  set  the  other  field  to 
the  same  value. 


UstSize 


Number  of  entries  in  the  list.  A  value  of  $FFFF  tells  the  List  Manager  to 
use  the  value  currently  stored  in  the  list  control  record. 
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NextMember2     $121C 

Searches  a  specified  list  record,  starting  with  a  specfied  item,  and  returns  the  item  number 
corresponding  to  the  next  selected  item.  This  call  accepts  an  item  number  and  control 
handle  as  input.  If  you  pass  an  item  number  of  0,  the  List  Manager  starts  its  search  from 
the  beginning  of  the  list. 


Parameters 

Stack  before  call 

Previous  contents 

Space 

Word— Space  for  result 

itemNum 

Word— Item  number  of  starting  point  for  search 

-      ctlHandle     - 

Long— Handle  of  the  list  control 

<— SP 

Stack  after  call 

Previous  contents 

itemNum 

Word— Item  number  of  selected  member;  0  if  no 

<— SP 

Errors                  None 

C 

exte 

en  pascal  Word  NextMember2 (itemNum,    ctlHa 

Word      itemNum; 
Handle    ctlHandle; 
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ResetMember2     $131C 

Searches  a  specified  list  control,  starting  with  the  first  list  member,  and  returns  the  item 
number  of  the  first  selected  member  in  the  list.  If  the  user  has  not  selected  a  member,  then 
the  returned  item  number  is  0.  This  call  accepts  a  control  handle  as  input. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlHandle 


Stack  after  call 


Word— Space  for  result 
Long— Handle  of  the  list  control 
<— SP 


Previous  contents 


itemNum 


Errors 
C 


Word— Item  number  of  selected  member;  0  if  no  more 
<— SP 

None 

extern  pascal  Word  ResetMember2 (ctlHandle) ; 
Handle    ctlHandle; 
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SelectMember2     $l4lC 

Selects  a  specified  member,  deselects  any  other  selected  members  of  the  list,  and  scrolls 
the  list  display  so  that  the  specified  member  is  at  the  top  of  the  display.  This  call  accepts 
a  control  handle  and  an  item  number  as  input. 

Parameters 

Stack  before  call 


Previous  contents 


itemNum 


ctlHandle     - 


Stack  after  call 


Word— Item  number  of  member  to  select 
Long— Handle  of  the  list  control 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SelectMember2 (itemNum, 
ctlHandle)  ; 

Word      itemNum; 
Handle    ctlHandle; 
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SortList2     $151C 


Alphabetizes  a  specified  list  by  rearranging  the  array  of  member  records.  This  call  accepts 
a  control  handle  and  a  pointer  to  a  custom  comparison  routine  as  input. 


Parameters 

Stack  before  call 

<s 

Previous  contents 

-     comparePtr    - 

Long— Pointer  to  comparison  routine;  NIL  for  standard  cc 

-      ctlHandle      - 

Long— Handle  of  the  list  control 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C 

exte 

rn  pascal  void  SortList2 (comparePtr,    ctlHandle); 

Pointer   comparePtr; 
Handle    ctlHandle; 
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Chapter  36  Memory  Manager  Update 


This  chapter  documents  new  features  of  the  Memory  Manager.  The 
complete  reference  to  the  Memory  Manager  is  in  Volume  1,  Chapter  12  of 
the  Apple  UGS  Toolbox  Reference. 
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Error  correction 


On  page  12-10  of  the  Toolbox  Reference,  Figure  12-7  shows  the  low-order  bit  of  the  User  ID 
is  reserved.  This  is  not  correct.  The  figure  should  show  that  the  mainiD  field  comprises 
bits  0-7,  and  that  the  mainiD  value  of  $00  is  reserved. 


Clarification 

The  Toolbox  Reference  documentation  of  the  SetHandieSize  call  ($1902)  states  "If  you 
need  more  room  to  lengthen  a  block,  you  may  compact  memory  or  purge  blocks."  This  is 
misleading.  In  fact,  to  satisfy  a  request  the  Memory  Manager  will  compact  memory  or 
purge  blocks  in  order  to  free  sufficient  contiguous  memory.  Therefore,  the  sentence 
should  read  "If  your  request  requires  more  memory  than  is  available,  the  Memory  Manager 
may  compact  memory  or  purge  blocks,  as  needed." 


New  features  in  the  Memory  Manager 

The  Memory  Manager  allocates  handles  much  faster  than  before.  The  Memory  Manager 
remembers  the  last  handle  allocated,  and  starts  its  search  for  new  memory  from  that 
location,  resulting  in  improved  allocation  time. 


Out-of-memory  queue 


The  out-of-memory  queue  allows  application  code  to  gracefully  recover  from  low- 
memory  conditions  in  the  system.  The  out-of-memory  queue  consists  of  a  series  of  out- 
of-memory  routines,  which  are  created  and  installed  by  application  programs.  When  the 
Memory  Manager  cannot  create  a  handle  from  memory  currently  available,  it  calls  each  of 
the  out-of-memory  routines.  These  routines  can  then  either  free  up  memory  that  is  not 
crucial  to  the  function  of  an  application,  or  notify  the  application  that  it  is  time  to  tell 
the  user  to.save  and  exit. 
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When  the  Memory  Manager  encounters  a  low-memory  condition,  it  performs  the  following 
steps: 

1 .  Invokes  each  out-of-memory  routine  until  a  routine  reports  that  it  has  freed  enough 
memory  to  satisfy  the  request.  If  a  routine  does  free  enough  memory,  the  Memory 
Manager  then  allocates  the  handle  and  returns  control  to  the  calling  application. 

2.  Compacts  memory  and  retries  the  allocation.  If  the  allocation  is  successful,  the 
Memory  Manager  returns  control  to  the  calling  application. 

3.  Purges  Level  3  handles.  If  this  frees  enough  memory,  the  Memory  Manager  compacts 
memory,  allocates  the  handle,  and  returns  to  the  ailing  application. 

4.  Purges  Level  2  handles.  If  this  frees  enough  memory,  the  Memory  Manager  compacts 
memory,  allocates  the  handle,  and  returns  to  the  calling  application. 

5.  PurgesLevel  1  handles.  If  this  frees  enough  memory,  the  Memory  Manager  compacts 
memory,  allocates  the  handle,  and  returns  to  the  calling  application. 

6.  Again  invokes  each  out-of-memory  routine.  If  a  routine  frees  enough  memory,  the 
Memory  Manager  allocates  the  handle  and  returns  to  the  application.  Otherwise,  the 
Memory  Manager  reports  an  out-of-memory  condition  to  the  application. 

Note  that  the  Memory  Manager  may  invoke  an  out-of:memory  routine  twice  during  the 
same  low-memory  condition.  In  the  invokation  parameter  block  for  an  out-of-memory 
routine,  the  Memory  Manager  passes  a  flag  indicating  whether  this  is  the  first  or  second 
time  through  the  out-of-memory  queue.  By  examining  this  flag,  routines  can  react 
differently  based  upon  the  urgency  of  the  low-memory  condition. 

Any  application,  desk  accessory,  or  init  that  installs  an  out-of-memory  routine  must  also 
remove  that  routine  from  the  out-of-memory  queue.  Add  routines  to  the  queue  with  the 
AddToOOMQueue  tool  call;  remove  them  with  the  RemoveFromOOMQueue  tool  call. 

Out-of-memory  routines  may  use  any  Memory  Manager  tool  call.  However,  routines  that 
must  issue  calls  that  allocate  memory  (such  as  NewHandie)  should  reserve  the  needed 
memory  at  initialization,  so  that  the  space  will  be  available  during  a  low-memory 
condition.  For  example,  if  you  want  your  out-of-memory  routine  to  save  some  user  data 
to  disk  before  purging  a  memory  block,  your  application  should  reserve  enough  memory 
for  the  file  open  before  installing  the  routine.  When  the  routine  gains  control,  it  can  then 
free  the  reserved  memory,  issue  the  file  system  calls,  and  purge  the  unneeded  application 
memory  without  creating  a  recursive  low-memory  condition.  See  the  code  example  for 
sample  application  and  out-of-memory  routine  code. 
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An  out-of-memory  routine  must  be  preceded  by  a  header  formatted  as  follows: 


$00 

$04 
$06 


Reserved 


version 


signature  — 


Long— Used  by  system  as  link  to  next  queue  item 

Word— Must  be  set  to  0 

Word— Header  signature,  to  ensure  integrity— set  to  $A55A 


version 


Allows  system  to  discriminate  between  current  and  future  types  of 
out-of-memory  routines.  Must  be  set  to  0. 


signature  Used  by  the  system  to  ensure  that  the  header  is  well-formed.  The  value 

of  this  field  must  be  $A55A. 

The  out-of-memory  routine  code  must  immediately  follow  the  signature  word.  If  the 
Memory  Manager  finds  an  invalid  header  for  any  out-of-memory  routine,  it  terminates 
with  a  system  death  error  code  of  $0209. 

When  the  out-of-memory  routine  gets  control,  the  Memory  Manager  will  have  formatted 
the  input  stack  as  follows: 


Previous  contents 


Space 


-    bytesNeeded    - 


stage 


RTLAddr      - 


stage 


Long— Space  for  result 

Long— Number  of  bytes  the  Memory  Manager  needs 
Word— Flagword  indicating  stage  of  low-memory  condition 
3  Bytes— Return  address 
<— SP 


Indicates  the  stage  of  the  low-memory  condition.  This  flag  allows  the 
routine  to  determine  whether  this  is  the  first  or  second  invokation  for 
this  condition.  If  the  field  is  set  to  0,  then  this  is  the  first  invokation, 
and  the  Memory  Manager  has  not  done  anything  else.  If  the  field  is  set 
to  1,  then  this  is  the  second  invokation  for  this  low-memory 
condition,  and  the  Memory  Manager  will  report  an  out-of-memory 
condition  to  the  calling  application  if  it  cannot  find  enough  memory 
to  satisfy  the  request. 
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The  out-of-memory  routine  must  strip  off  the  input  parameters  and  return  the  number  of 
bytes  freed  in  the  space  provided.  On  exit,  therefore,  the  routine  should  format  the  stack 
as  follows: 


Previous  contents 


-   amountFreed   - 


RTLAddr      - 


Long— Number  of  bytes  of  memory  freed  by  routine 

3  Bytes— Return  address 
<— SP 


Out-of-memory  Routine  example 

The  following  code  example  has  two  parts:  the  first  shows  how  your  application  can  install 
a  routine  in  the  out-of-memory  queue;  the  second  is  a  sample  out-of-memory  routine. 


first  allocate  a  handle  with  enough  memory  for  our  low  memory  exit 
this  example  will  use  a  16k  handle 


room  for  result  ' 


pha 

pha 

PushLong  #$4000 

PushWord  MylD 

PushWord  #0 

PushLong  #0 

_NewHandle 

PullLong  ResvHand  ;  and  pull  off  the  reserve  handle 


size  of  handle 

my  applications  ID 

no  bits  set,  unlocked  and  moveable 

address  (Not  used) 


PushLong  #MyOOMRtn 
AddToOOMQueue 


;  address  of  the  OOM  header 


st z  OOMFlag 


;  zero  our  low  memory  indicator 


Note  that  this  application  maintains  the  OOMFlag  field  in  its  global  storage  area. 
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The  following  is  the  actual  out-of-memory  queue  entry  itself.  It  has  been  written  for  the 
MPW™  Apple  IIGS  assembler. 


This  is  the  OOMQueue  header  for  our  routine 


MyOOMRtn    Record 
dc.L  0 
dc.W  0 
dc.W  $A55A 
EndR 


;  used  by  queue  manager 

;  OOMEntry  version 

;  queue  entry  signature 


Now  for  my  out-of-memory  routine 


MyOOM 


proc 


first  set  up  the  equates  for  the  stack  frame  passed  to  us  by  the 
memory  mgr 


RTLAdr      equ  1  ;  return  address  we  will  go  back  to 

Stage       equ  RTLAdr+3  ;  indicates  when  called 

BytesNeeded  equ  Stage+2  ;  number  of  bytes  the  mem  mgr  needs 

Result      equ  BytesNeeded+4  ;  return  number  of  bytes  freed 


before  we  start  we  should  zero  out  the  result 


Ida  #0 

sta  Result, s 

sta  Result+2,s 


;  zero  the  result  on  the  stack 


Since  this  routine  can  be  called  before  and  after  purging  data 

we  want  to  wait  till  the  memory  manager  has  purged  everything  it  can 

before  we  panic  so  the  first  thing  we  do  is  test  the  Stage 


Ida  Stage, s 
beq  OOMEnd 


;  get  the  passed  stage 

;  if  0  then  don't  free  anything 


Now  that  we  know  that  the  memory  manager  has  tried  everything  else, 
we  test  to  see  if  we  have  done  this  before  by  testing 
the  OOMFlag 


Ida  >OOMFlag 
bne  OOMEnd 


;  must  use  long  address  DB=unknown 

;  if  non-zero  then  memory  already  free 
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since  we  know  that  we  have  not  freed  the  reserve  memory  yet 
we  will  do  so  now  and  set  the  flag. 

PushLong  >ResvHand      ;  handle  to  our  reserve  space 
_DisposeHandle     ;  and  dispose  of  it 


Ida  #$FFFF 
sta  >OOMFlag 


;  now  set  our  flag  to  true 

;  so  that  the  event  loop  knows  low  mem 


Ida  #$4000 
sta  Result, s 


and  signal  the  memory  manager  how 
much  mem  we  freed 


;  Now  return  to  the  memory  manager  first  adjusting  the  stack  to  remove 

the 

;  passed  params 


OOMEnd 


LongA 

Off 

SEP  #$20 

pla 

ply 

plx 

plx 

plx 

phy 

pha 

LongA 

On 

REP  #$20 

;  turn  on  8  bit  accumulator 


;  load  the  return  address  for  safe 
;  keeping  for  a  sec 

;  now  pull  off  6  bytes  of  parameters 


;  put  the  return  addr  back 


;  turn  on  16  bit  accumulator 


RTL 


;  and  return 
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New  Memory  Manager  calls 

ReaiFreeMem  is  a  new  Memory  Manager  call  designed  to  provide  accurate  information 
about  available  memory.  Other  new  Memory  Manager  calls  support  the  out-of-memory 
queue. 


AddToOOMQueue     $0C02 

Adds  the  specified  out-of-memory  routine  to  the  head  of  the  out-of-memory  queue.  The 
input  routine  pointer  should  contain  the  address  of  the  routine  header  block. 

Parameters 

Stack  before  call 


Previous  contents 


headerPtr 


Long— Pointer  to  out-of-memory  routine 
<-SP 


Stack  after  call 


Previous  contents 


Errors 


$0381 


<— SP 
invalidTag 


Correct  signature  value  not  found 
in  header 


extern  pascal  void  AddToOOMQueue (headerPtr) ; 
Pointer        headerPtr; 
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RealFreeMem    $2F02 

Returns  the  number  of  bytes  in  memory  that  are  free,  plus  the  number  that  could  be  made 
free  by  purging.  FreeMem  only  returns  the  number  of  bytes  that  are  actually  free,  ignoring 
memory  that  is  occupied  by  unlocked  purgeable  blocks.  Since  unlocked  blocks  of 
allocated  memory  can  be  freed  by  purging,  FreeMem  does  not  provide  an  accurate 
picture  of  the  memory  that  is  actually  available.  RealFreeMem  provides  a  more  accurate 
value. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Long— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


freeBytes 


Errors 
C 


Long— Number  of  available  bytes  in  memory 
<— SP 

None 

extern  pascal  Long  RealFreeMem  () ; 
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RemoveFromOOMQueue     $0D02 


Removes  the  specified  out-of-memory  routine  from  the  queue.  The  input  routine  pointer 
should  contain  the  address  of  the  routine  header  block. 

Parameters 

Stack  before  call 


Previous  contents 


headerPtr 


Long— Pointer  to  out-of-memory  routine 
<— SP 


Stack  after  call 

Previous  contents 

<— SP 

Errors                  $0381 

invalidTag 

$0380 

notlnList 

Correct  signature  value  not  found 

in  header 

Specified  routine  not  found  in 

queue 

extern  pascal  void  RemoveFromOOMQueue (headerPtr) ; 
Pointer   headerPtr; 
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Chapter  37  Menu  Manager  Update 


This  chapter  documents  new  features  of  the  Menu  Manager.  The 
complete  reference  to  the  Menu  Manager  is  in  Volume  1,  Chapter  13  of 
the  Apple  IIGS  Toolbox  Reference. 
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Error  corrections 

■  In  the  description  of  the  setSysBar  tool  call  (pages  13-86  and  13-3),  the  Toolbox 
Reference  states  that,  after  an  application  issues  this  call,  the  new  system  menu  bar 
becomes  the  current  menu  bar.  This  is  incorrect.  Your  application  must  issue  the 
setMenuBar  tool  call  to  make  the  new  menu  bar  the  current  menu  bar. 

■  In  the  definition  of  the  menu  bar  record  (pages  13-17-18),  the  Toolbox  Reference  shows 
that  bits  0-5  of  the  ctiFlag  field  are  used  to  indicate  the  starting  position  for  the 
first  title  in  the  menu  bar.  This  is  incorrect.  The  otiHiiite  field  defines  the  starting 
position  for  the  first  title.  Note  further  that  the  entire  ctiHiiite  field  is  used  in  this 
manner.  The  documented  purpose  of  the  ctiHiiite  field  (number  of  highlighted 
titles)  is  not  supported  by  the  Menu  Bar  record. 


Clarifications 

The  setBarCoiors  tool  call  changes  the  color  table  for  all  menu  bars  in  a  window.  If 

you  want  to  use  separate  color  tables  for  different  menu  bars,  your  application  must 

build  a  menu  bar  color  table  and  modify  the  cticoior  field  of  the  appropriate 

control  record  to  point  to  this  custom  color  table.  See  "SetBarColor"  in 

Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for  the  format  and 

contents  of  a  menu  bar  color  table. 

The  description  of  the  insertMenu  tool  call  should  also  note  that  your  application 

must  call  FixMenuBar  before  calling  DrawMenuBar  in  order  to  display  the  modified 

menu  bar. 

The  description  of  the  mitPaiette  tool  call  in  the  Toolbox  Reference  should  also 

note  that  the  call  changes  color  tables  1  through  6  to  correspond  to  the  colors  needed 

for  drawing  the  Apple  logo  in  its  standard  colors. 

The  CaicMenuSize  call  uses  the  newWidth  and  newHeight  parameters  to  compute  a 

menu's  size.  These  parameters  may  contain  the  width  and  height  of  the  menu,  or  may 

contain  the  values  $0000  or  $FFFF.  A  value  of  $0000  tells  c<      MenuSize  to  calculate 

the  parameter  automatically.  A  value  of  $FFFF  tells  it  to  calculate  the  parameter  only  if 

the  current  setting  is  0. 
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The  effect  of  all  three  uses: 

n   Pass  the  new  value.  The  value  passed  will  become  the  menu's  si2e.  Use  this 

method  when  a  specific  menu  size  is  needed. 
o   Pass  $0000.  The  size  value  will  be  automatically  computed.  This  option  is  useful  if 

menu  items  are  added  or  deleted,  rendering  the  menu's  size  incorrect.  The  menu's 

height  and  width  can  be  automatically  adjusted  by  calling  caicMenuSize  with 

newWidth  and  newHeight  equal  to  $0000. 
d   Pass  $FFFF.  The  width  and  height  of  a  menu  is  0  when  it  is  created.  FixMenuBar 

calls  CaicMenuSize  with  newWidthznd  newHeight  equal  to  $FFFF  to  calculate 

the  sizes  of  those  menus  with  heights  and  widths  of  0. 
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New  features  in  the  Menu  Manager 


This  section  lists  several  new  features  of  the  Menu  Manager,  and  some  information  that 
was  not  previously  clear. 

■  Menus  in  windows  can  now  display  the  Apple  character  (ASCII  $14),  though  it  will  not 
be  multicolored. 

■  Menus  now  use  their  outline  color  for  lines  that  separate  menu  items. 

■  The  NewMenuBar  call  automatically  sets  bit  31  of  the  etiowner  field  in  the  menu  bar 
record  to  1,  if  the  designated  menu  bar  is  a  window  menu  bar  (the  value  passed  for  the 
window  is  not  0). 

■  The  default  position  for  the  first  menu  title  in  a  menu  bar  is  10  pixels  indented  from  the 
left  edge  of  the  screen,  in  640  mode;  in  320  mode  the  item  is  indented  5  pixels. 

■  The  Menu  Manager's  justification  procedures  adjust  for  menu  bars  in  windows.  Menus 
will  be  moved  to  the  left  if  they  would  otherwise  appear  to  the  right  of  the  menu  bar's 
right  end. 

■  The  default  menu  bar  has  the  following  coordinates:  top  -  0;  left  -  0;  height  -  13; 
width  -  the  width  of  the  screen. 

■  MenuShutDown  does  not  return  an  error  if  the  Menu  Manager  has  already  been  shut 
down. 

■  Your  application  can  now  create  empty  menus.  To  create  an  empty  menu,  set  the  first 
byte  in  the  first  menu  line  item  to  either  null  ($00)  or  return  ($0D),  signifying  the  end  of 
the  menu  definition.  For  example: 

dc.b   '$$  Empty  Menu  \N1',$00  ;  menu  title  and  ID 
dc.b  $00  ;  first  character  in  first 

item  to  null  (or  return) 
indicates  end  of  menu  def . 


version 

menu  id 

menu  flag 

menu  title 

indicates  end  of  item  list 


Or,  using  a  menu  template: 

EmptyMenu 

dc.W 

0 

dc.W 

1 

dc.W 

0 

dc.L 

Title 

dc.L 

$00000000 

Title  str 

'Empty  Menu' 
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The  Menu  Manager  now  correctly  supports  outline  and  shadow  text  styles.  As  a  result, 

the  existing  Toolbox  Reference  description  of  the  setMitemstyle  tool  call,  and  the 

menu  text  style  word  defined  in  that  description,  is  now  correct. 

In  addition,  the  Menu  Manager  now  supports  two  new  special  characters  for  menu 

definition: 

O  Outline  the  text 

S    Shadow  the  text 
Other  special  characters  are  listed  on  page  13-14  of  Volume  1  of  the  Toolbox  Reference. 
Note  that  this  feature  requires  the  QuickDraw  II  Auxiliary  Tool  Set. 

Menus  now  scroll  up  or  down  if  their  items  will  not  fit  on  the  screen.  When  a  menu  is 
scrollable  in  a  direction,  an  arrow  indicator  appears  at  the  appropriate  end  of  the 
menu,  signifying  that  there  are  more  items  available.  See  Figure  37-1. 

The  indicator  does  not  highlight,  but  the  menu  contents  scroll  when  the  user  drags  over 
it.  When  the  last  item  is  displayable,  the  indicator  disappears.  Indicators  may  appear 
at  both  the  top  and  bottom  of  a  menu,  if  appropriate. 

Menus  scroll  at  two  speeds,  depending  upon  where  the  user  drags  in  the  indicator.  If 
the  user  drags  within  the  first  five  pixels  of  an  indicator,  scrolling  runs  at  its  slow  speed. 
Dragging  anywhere  beyond  this  point  results  in  fast  scrolling. 

Figure  37-1      Scrolling  menus  with  indicator  at  bottom 
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♦   Note:  If  your  application  defines  menus  within  a  moveable  window,  dragging  that 
window  close  to  the  bottom  of  the  screen  may  force  some  of  the  menus  to  be 
scrollable.  If  there  is  not  room  for  three  visible  items  (up  and  down  indicators  and  one 
menu  item),  then  the  menu  will  drop  below  the  visible  screen  area. 
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The  menu  record  has  been  slightly  modified.  The  f  irstitem  and  numof  items  byte 
fields  have  been  combined  into  a  single  word  field,  numof  items,  at  offset  $0C  into 
the  record.  This  field  specifies  the  number  of  items  in  the  menu. 

Bit  8  of  the  flag  field  in  the  menu  record  is  now  defined  as  the  alwaysCaiimChoose 
flag.  When  this  flag  is  set  to  1,  the  Menu  Manager  calls  the  mChoose  routine  in  the 
defProc  for  a  custom  menu  even  when  the  mouse  is  not  within  the  menu  rectangle.  This 
feature  supports  tear-off  menus. 

Keyboard  equivalents  and  check  marks  now  appear  in  plain  text  regardless  of  the  style 
of  the  associated  menu  item. 

The  Menu  Manager  can  now  handle  large  fonts  in  menus. 


Menu  caching 

The  current  version  of  the  Menu  Manager  introduces  new  menu  caching  features.  Menu 
caching  is  designed  to  provide  faster  display  of  menus  under  certain  circumstances.  When 
a  menu  is  drawn  on  the  screen,  the  area  of  the  screen  that  it  covers  is  copied  into  a  buffer. 
When  the  menu  goes  away,  the  contents  of  the  buffer  are  copied  back  to  the  screen. 

With  the  menu  caching  feature,  when  the  saved  screen  image  is  copied  back  to  the  screen, 
the  menu  that  goes  away  is  copied  into  the  buffer.  In  other  words,  the  Menu  Manager 
swaps  the  menu  image  with  the  screen  image.  Therefore,  the  next  time  that  menu  is  pulled 
down,  the  Menu  Manager  can  copy  it  from  the  buffer  instead  of  drawing  a  new  image. 

If  the  menu  image  changes— for  example,  an  item  is  disabled  or  the  items  on  the  menu 
change — then  the  cached  image  is  inaccurate,  and  the  Menu  Manager  must  redraw  the 
menu.  In  those  cases  where  a  menu  image  does  not  change,  the  menu  bar  can  respond  to 
the  user  more  quickly. 

Menu  caching  should  not  increase  memory  requirements,  because  menu  images  are 
purgeable  when  not  displayed  on  the  screen. 

This  menu  caching  scheme  should  work  properly  with  all  existing  standard  menus.  You  will 
have  to  alter  custom  menus,  however,  so  that  they  can  take  advantage  of  menu  caching. 
Custom  menus  will  still  function  normally,  as  long  as  they  do  not  change  the  menu  record 
directly,  but  they  will  not  be  able  to  take  advantage  of  the  menu  caching  scheme  to  speed 
up  display. 

Caching  does  not  work  with  menus  in  windows,  so  the  insertMenu  call  automatically 
disables  caching  for  such  menus. 
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Caching  with  custom  menus 

Bit  3  of  the  MenuFlag  field  in  a  menu  record  indicates  whether  a  menu's  definition 
procedure  knows  about  caching.  A  value  of  1  indicates  that  the  menu  in  question  is 
cacheable.  A  custom  menu  that  uses  caching  must  definea  menu  record  that  sets  this  flag 
and  allocates  an  extra  field,  a  handle  to  the  cache  in  which  the  menu  image  will  be  stored, 
as  shown  in  the  following  figure. 


$00 

menuID 

- 

$02 

menuWidth 

- 

$04 

menuHeight 

- 

$06 

menuProc 

— 

$0A 

menuFlag 

$0B 

menuRes 

$0C 

numOfltems 

- 

$0E 

titleWidth 

- 

$10 

- 

tltleName 

~ 

$14 

— 

menuCache 

- 

Word— Menu's  ID  number 
Word— Width  of  menu 
Word— Height  of  menu 

-   Long— Pointer  to  menu  definition  procedure 

Byte— Flags  (bit  3  set  to  1  for  cached  menus) 
Byte— Reserved 

Word— Number  of  menu  items 
Word— Width  of  title 

Long— Pointer  to  title  string  for  menu 
Long— Handle  to  cache  for  menu  image 
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Pop-up  menus 

Menu  Manager  now  supports  pop-up  menus.  Pop-up  menus  exist  in  a  window,  not  in  the 
menu  bar.  Figure  37-2  shows  a  window  with  pop-up  menus.  The  screen  representation  of  a 
pop-up  is  a  box  with  a  one-pixel-thick  drop  shadow.  When  the  user  clicks  the  mouse 
inside  the  pop-up  box,  the  menu  appears,  with  the  current  value  highlighted  under  the 
arrow,  as  shown  in  Figure  37-3.  If  the  menu  has  a  title,  the  tide  is  highlighted  whenever  the 
menu  is  visible. 

Pop-up  menus  work  in  the  same  way  as  other  menus:  the  user  can  move  around  within  the 
menu,  select  an  item  by  positioning  over  it,  or  not  select  any  item  by  dragging  outside  the 
menu.  Pop-up  menus  support  scrolling,  if  it  is  needed  to  view  all  the  menu  items.  Pop-up 
menus  are  useful  for  setting  values  or  choosing  from  lists  of  related  values. 

Pop-up  menus  support  most  of  the  standard  features  and  calls  available  with  standard 
menus: 

Pop-up  menu  items  support  keystroke  equivalents.  Pop-up  menus  will  display  the 
equivalent  (Apple  logo  with  character).  Note  that  if  a  pop-up  item's  keystroke 
equivalent  conflicts  with  a  standard  menu  item  equivalent,  the  pop-up  menu  may  not 
receive  the  keystroke.  TaskMaster  passes  the  keystroke  to  the  system  first,  unless  the 
tmControiKey  flag  in  the  wmTaskMask  field  of  the  task  record  is  set  to  0  (do  not 
pass  keys  to  controls  in  the  active  window). 

Pop-up  menu  items  can  be  dimmed  to  indicate  that  they  are  disabled  and  cannot  be 
chosen. 

Each  item  in  a  pop-up  menu  can  have  its  own  text  styles. 
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Figure  37-2      Window  with  pop-up  menus 
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Figure  37-3      Dragging  through  a  pop-up  menu 
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Pop-up  menu  scrolling  options 

There  are  two  types  of  pop-up  menus,  which  are  distinguished  by  their  support  for 
scrolling:  type  1  pop-up  menus  and  type  2  pop-up  menus. 

The  Menu  Manager  determines  the  size  rectangle  into  which  to  draw  a  type  1  pop-up  menu 
based  upon  the  relative  position  of  the  current  item  within  the  menu  and  the  window 
constraints  of  the  pop-up  menu  (see  Figure  37-4).  The  Menu  Manager  draws  the  pop-up 
menu  with  the  current  item  highlighted  and  positioned  adjacent  to  the  menu  title.  The 
menu  extends  up  and  down  only  as  far  as  is  necessary  to  display  the  remaining  items  in 
each  direction,  and  indicators  as  appropriate,  within  the  boundary  rectangle  for  the 
window.  Therefore,  with  type  1  pop-up  menus,  it  is  possible  to  obtain  a  display  such  as 
that  shown  in  Figure  37-4,  where  the  user  can  display  only  a  single  item. 
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Figure  374      Type  1  pop-up  menu 
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When  the  Menu  Manager  needs  to  make  a  type  2  pop-up  menu  scrollable,  it  creates  a  menu 
that  is  long  enough  to  receive  all  the  menu  items,  within  the  bounds  of  the  screen.  In  this 
manner,  the  user  never  sees  a  menu  with  too  few  item  lines  to  be  useful.  Figure  37-5  shows 
how  the  Baud  rate  pop-up  menu  from  Figure  37-4  would  appear  if  it  had  been  defined  as  a 
type2  pop-up  menu. 
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Figure  37-5      Type  2  pop-up  menu 
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By  dragging  over  the  scroll  indicator,  the  user  can  eventually  scroll  all  menu  items  that  will 
fit  on  the  screen  into  view,  regardless  of  menu  proximity  to  top  or  bottom  of  screen. 

How  to  use  pop-up  menus 

Your  application  can  define  pop-ups  in  two  ways:  either  as  controls  or  menus. 

If  your  application  defines  its  pop-ups  as  controls,  using  the  NewControi2  Control 
Manager  tool  call,  then  drawing,  updating,  resizing,  and  tracking  will  all  be  handled  by 
TaskMaster  and  TrackControi  automatically.  TaskMaster  will  also  deal  with  any 
keystroke  equivalents  you  have  defined.  See  Chapter  28,  "Control  Manager  Update,"  for 
details  on  how  to  create  a  pop-up  control  template  and  invoke  NewControi2. 

If,  on  the  other  hand,  your  application  defines  its  pop-ups  as  menus,  it  gains  flexibility 
but  has  more  responsibility.  Your  application  must  draw  the  pop-up  box  and  title, 
highlight  the  title,  recognize  mouse-down  events  in  the  pop-up  box  or  title,  and  change 
the  current  entry  in  response  to  user  choices.  Your  application  must  also  deal  with 
keystroke  equivalents.  Once  your  program  detects  a  mouse-down  event  inside  the  Pop- 
up box  or  title,  it  must  call  PopupMenuSeiect  to  display  the  menu  and  track  the  mouse. 
This  call  returns  the  item  ID  of  the  selected  item  (0  if  none  selected).  Your  program  can 
use  this  item  ID  to  determine  which  item  was  selected.  Your  program  must  pass  this  item 
ID  to  PopupMenuSeiect  the  next  time  the  user  clicks  in  the  pop-up. 
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♦   Note:  When  you  create  a  pop-up  control  with  NewControi2,  calling  setMitem, 
SetMItem2,  SetMItemName,  SetMItemName2,  SetMItemStyle, 
setMenuTitie  or  setMenuTitie2  does  not  change  the  appearance  of  the  pop-up 
until  the  pop-up  is  redrawn.  If  your  application  changes  the  pop-up  title,  the  system 
does  not  change  the  control  rectangle  to  account  for  a  length  change.  To  resize  the 
control  rectangle,  your  program  must  dispose  of  the  existing  control  and  create  a  new 
one  with  NewControl2. 

Table  37-1  lists  the  Menu  Manager  routines  that  work  with  pop-up  menus.  Refer  to  the  call 
descriptions  in  either  the  Toolbox  Reference  or  in  this  chapter  for  details  on  each  call. 


Table  37-1        Menu  Manager  calls  that  work  with  pop-up  menus 


CalcMenuSize 

CheckMItem 

CountMItems 

DeleteMItem 

DisableMItem 

EnableMItem 

GetMenuFlag 

GetMenuTitle 

GetMHandle 

GetMItem 

GetMItemFlag 

GetMItemMark 

GetMItemStyle 

GetMTitleWidth 

InsertMItem 

SetMenuBar 

SetMenuFlag 

SetMenuID 

SetMenuTitie 

SetMenuTitle2 

SetMitem 

SetMItem2 

SetMItemBlink 
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SetMItemFlag 

SetMItemMark 

SetMItemName 

SetMItemName2 

SetMItemStyle 

SetMTitleWidth 

Each  of  the  routines  listed  in  Table  37-1  operate  on  the  current  menu  bar.  If  your 
application  defined  its  pop-ups  using  NewControi2,  then  it  must  set  the  pop-up  to  be 
the  current  menu,  by  issuing  the  setMenuBar  call  and  specifying  the  control  handle  for 
the  pop-up  as  input. 

If  your  application  uses  PopUpMenuSeiect,  rather  than  NewControi2,  then  it  must 
insert  the  pop-up  menu  into  the  current  menu  bar  by  calling  insertMenu,  issue  the 
desired  Menu  Manager  tool  calls,  then  remove  the  pop-up  menu  from  the  menu  bar  by 
calling  DeieteMenu.  Your  program  passes  the  handle  to  the  pop-up  menu  to  each  of 
these  routines. 


37-14     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


New  Menu  Manager  data  structures 

The  new  Menu  Manager  calls  allow  you  to  define  menus  using  templates,  analogous  to  the 
templates  used  by  the  NewControi2  Control  Manager  tool  call,  which  can  then  be  stored 
in  fixed  memory,  in  allocated  memory  referenced  by  handle,  or  in  resources.  When  using 
any  of  these  new  calls,  your  program  must  specify  the  input  data  according  to  these 
templates. 

♦   Note:  Any  strings  referenced  in  these  data  structure  descriptions  are  Pascal  strings. 
Note  as  well  that  all  flag  bit  definitions  are  backward  compatible.  That  is,  no  existing 
bits  have  been  redefined.  In  addition,  note  that  the  menuFlag  field  is  now  defined 
as  a  word,  rather  than  a  byte.  The  byte  following  the  old  menuFlag  byte,  menuRes, 
was  never  used,  and  has  been  collapsed  into  menuFlag. 


Menu  item  template 

Figure  37-'6  shows  the  template  that  defines  the  characteristics  of  a  menu  item.  Use  it  with 
new  Menu  Manager  calls  that  require  menu  item  templates. 


Figure  37-6      Menu  item  template 


$00 

version 

- 

$02 

$04 
$05 

itemlD 

- 

itemChar 

itemAltChar 

$06 

itemCheck 

- 

$08 

iteraFlag 

- 

$0A 

-~ 

iteraTitleRef 

: 

Word— Version  number  for  template;  must  be  set  to  0 

Word— Menu  item  ID 

Byte— Primary  keystroke  equivalent  character 
Byte— Alternate  keystroke  equivalent  character 

Word— Character  code  for  checked  items 
_   Word— Menu  item  flag  word 

-   Long— Reference  to  item  title  string 


version 


Identifies  the  version  of  the  menu  item  template.  The  Menu  Manager 
uses  this  field  to  distinguish  between  different  revisions  of  the  menu 
item  template.  Must  be  set  to  0. 
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itemID 


Unique  identifier  for  the  menu  item.  See  Chapter  13,  "Menu  Manager," 
in  the  Toolbox  Reference  for  information  on  valid  values  for  itemiD. 


itemChar,  itemAltChar 

These  fields  define  the  keystroke  equivalents  for  the  menu  item.  The 
user  can  select  the  menu  item  by  pressing  the  Command  key  along  with 
the  key  corresponding  to  one  of  these  fields.  Typically,  these  fields 
contain  the  upper  and  lower  case  ASCII  codes  for  a  particular 
character.  If  you  only  have  a  single  key  equivalence,  set  both  fields 
with  that  value. 


itemCheck 


itemFlag 


titleRefType 


Defines  the  character  to  be  displayed  next  to  the  item  when  it  is 
checked. 

Bit  flags  controlling  the  display  attributes  of  the  menu  item.  Valid 
values  for  itemFlag  are: 


bits  14-15 


Reserved 

bit  13 

shadow 

bit  12 

outline 

bit  11 

Reserved 

bits  8-10 

disabled 

bit? 

divider 

bit  6 

XOR 

bit  5 

Reserved 

bits  3-4 

underline 

bit  2 

Defines  the  type  of  reference  in  itemTitieRef : 

00  -  Reference  is  pointer 

01  -  Reference  is  handle 

10  -  Reference  is  resource  ID 

11  -  Invalid  value 
Must  be  set  to  0 
Indicates  item  shadowing: 

0  -  No  shadow 

1  -  Shadow 

Indicates  item  outlining 

0  -  Not  outlined 

1  -  Outlined 
Must  be  set  to  0 

Enables  or  disables  the  menu  item: 

0  -  Item  enabled 

1  -  Item  disabled 

Controls  drawing  divider  below  item: 

0  -  No  divider  bar 

1  -  Divider  bar 

Controls  how  highlighting  is  performed: 

0  -  Do  not  use  XOR  to  highlight 

1  -  Use  XOR  to  highlight  item 
Must  be  set  to  0 

Controls  item  underlining: 

0  -  Do  not  underline  item 

1  -  Underline  item 
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italic  bit  1  Indicates  whether  item  is  italicized 

0  -  Not  italicized 

1  -  Italicized 

bold  bit  0  Indicates  whether  item  is  drawn  bold: 

0  -  Not  bold 

1  -  Bold 

itemTitieRef    Reference  to  title  string  for  menu  item.  The  titieRef  Type  bits  in 
itemFlag  indicate  whether  itemTitieRef  contains  a  pointer,  a 
handle,  or  a  resource  ID.  If  itemTitieRef  is  a  pointer,  then  the  title 
string  must  be  a  Pascal  string.  Otherwise,  the  Menu  Manager  can 
retrieve  the  string  length  from  control  information  in  the  handle. 
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Menu  template 

Figure  37-7  shows  the  menu  template,  which  defines  the  characteristics  of  a  menu, 
including  its  menu  item  references.  Use  it  with  new  Menu  Manager  calls  that  require  menu 
templates. 


Figure  37-7      Menu  template 


$00 

—             version               — 

Word— Version  number  for  template;  must  be  set  to  0 

$02 

—             menuID               — 

Word— Menu  ID 

$04 

—            menuFlag              — 

Word— Menu  flag  word 

$06 

—       menuTitleRef         - 

Long— Reference  to  menu  title  string 

$0A 

itemRefArray 

n  Longs— References  to  menu  items 

version 


menuID 


menuFlag 


titleRefType 


Identifies  the  version  of  the  menu  template.  The  Menu  Manager  uses 
this  field  to  distinguish  between  different  revisions  of  the  template. 
Must  be  set  to  0. 

Unique  identifier  for  the  menu.  See  Chapter  13,  "Menu  Manager,"  in  the 
Toolbox  Reference  for  information  on  valid  values  for  menuiD. 

Bit  flags  controlling  the  display  and  processing  attributes  of  the  menu. 
Valid  values  for  menuFlag  are: 

bits  14-15   Defines  the  type  of  reference  in  menuTitleRef: 

00  -  Reference  is  pointer 

01  -  Reference  is  handle 

10  -  Reference  is  resource  ID 
11 -Invalid  value 
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itemRefType 


Reserved 
alwaysCallmChoose 


bits  12-13    Defines  the  type  of  reference  in  each  entry  of 

itemRef  Array  (all  array  entries  must  be  of  the  same 
type): 

00  -  References  are  pointers 

01  -  References  are  handles 

10  -  References  are  resource  IDs 
11 -Invalid  value 
bits  9-11     Must  be  set  to  0 


disabled 


Reserved 

bit  6 

XOR 

bit  5 

custom 

bit  4 

allowCache 

bit  3 

Reserved 


menuTitleRef 


itemRefArray 


bit  8  Causes  the  Menu  Manager  to  call  a  custom  menu 

defProc  mChoose  routine  even  when  the  mouse  is  not 
in  the  menu  rectangle  (supports  tear-off  menus): 

0  -  Do  not  always  call  mChoose  routine 

1  -  Always  call  mChoose  routine 
bit  7           Enables  or  disables  the  menu: 

0  -  Menu  enabled 

1  -  Menu  disabled 
Must  be  set  to  0 
Controls  how  selection  highlighting  is  performed: 

0  -  Do  not  use  XOR  to  highlight 

1  -  Use  XOR  to  highlight  item 
Indicates  whether  custom  or  standard  menu: 

0  -  Standard  menu 

1  -  Custom  menu 
Controls  menu  caching: 

0  -  Do  not  cache  menu 

1  -  Menu  caching  allowed 
bits  0-2      Must  be  set  to  0 

Reference  to  title  string  for  menu.  The  titieRef  Type  bits  in 
menuFlag  indicate  whether  menuTitleRef  contains  a  pointer,  a 
handle,  or  a  resource  ID.  If  menuTitleRef  is  a  pointer,  then  the  title 
string  must  be  a  Pascal  string.  Otherwise,  the  Menu  Manager  can 
retrieve  the  string  length  from  control  information  in  the  handle. 

Array  of  references  to  the  menu  items  for  the  menu.  The 
itemRefType  bits  in  menuFlag  indicate  whether  the  entries  in  the 
array  are  pointers,  handles,  or  resource  IDs.  Note  that  all  array  entries 
must  contain  the  same  reference  type.  The  last  entry  in  the  array  must 
be  set  to  $00000000. 
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Menu  bar  template 

Figure  37-8  shows  the  menu  bar  template,  which  defines  the  characteristics  of  a  menu  bar, 
including  its  menu  references.  Use  it  with  new  Menu  Manager  calls  that  require  menu  bar 
templates. 


Figure  37-8      Menu  bar  template 


$00 

$02 
$04 


—  version 


—         menuFlag 


Word— Version  number  for  template;  must  be  set  to  0 
Word— Menu  bar  flag  word 


menuRef  Array         '■  n  Longs— References  to  menus 


L 


version 


menuBarFlag 


menuRefType 


Reserved 


menuRef Array 


Identifies  the  version  of  the  menu  bar  template.  The  Menu  Manager 
uses  this  field  to  distinguish  between  different  revisions  of  the 
template.  Must  be  set  to  0. 

Bit  flags  controlling  the  display  and  processing  attributes  of  the  menu 
bar.  Valid  values  for  menuBarFlag  are: 

bits  14-15   Defines  the  type  of  reference  in  each  entry  of 

menuRef  Array  (all  array  entries  must  be  of  the  same 
type): 

00  -  References  are  pointers 

01  -  References  are  handles 

10  -  References  are  resource  IDs 

11  -  Invalid  value 
bits  0-13     Must  be  set  to  0 

Array  of  references  to  the  menus  for  the  menu  bar.  The  menuRefType 
bits  in  menuBarFlag  indicate  whether  the  entries  in  the  array  are 
pointers,  handles,  or  resource  IDs.  Note  that  all  array  entries  must 
contain  the  same  reference  type.  The  last  entry  in  the  array  must  be  set 
to  $00000000. 
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New  Menu  Manager  calls 

The  following  sections  discuss  the  various  new  Menu  Manager  tool  calls  in  alphabetical 
order  by  call  name. 


GetPopUpDefProc     $3B0F 


Returns  a  pointer  to  the  control  definition  procedure  for  pop-up  menus.  Your  application 
should  not  issue  this  call. 

The  system  issues  this  call  during  Control  Manager  start  up  processing  in  order  to  obtain 
the  address  of  the  pop-up  menu  definition  procedure. 


Parameters 

Stack  before  call 

Previous  contents 

Space 

Long— Space  for  result 

<— SP 

Stack  after  call 

Previous  contents 

-     defProcPtr     - 

Long— Pointer  to  control  procedure 

<— SP 

Errors                  None 

C 

exte 

m  pascal   Pointer  GetPopUpDefPro 
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HideMenuBar     $450F 

Hides  the  system  menu  bar,  by  adding  the  menu  bar  to  the  desktop  region.  This  call  sets 
the  invisible  flag  for  the  menu  bar,  resets  scan  lines  2  through  9  (which  had  been  changed 
to  correctly  display  the  colors  of  the  Apple  logo),  and  refreshes  the  desktop.  The  system 
ignores  all  subsequent  calls  to  DrawMenuBar  or  FiashMenuBar,  since  the  menu  bar  is 
invisible.  Use  the  showMenuBar  call  to  make  the  menu  bar  visible  again. 

Parameters 

Stack  before  call 


Previous  contents 


-SP 


Stack  after  call 


Previous  contents 


<— SP 

Errors  None 

C  extern  pascal  void  HideMenuBar () ; 
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InsertMItem2     $3F0F 

Inserts  a  menu  item  into  a  menu  after  a  specified  menu  item  or  at  the  top  of  the  menu. 
This  call  accepts  a  menu  item  template  for  its  input  specification. 

Parameters 

Stack  before  call 


Previous  contents 


refDescriptor 


-  menuItemTRef  - 


insertAfter 


menuNum 


Stack  after  call 


Word— Defines  type  of  reference  in  menuItemTRef 
Long— Reference  to  menu  item  template 
Word— ID  of  item  after  which  to  insert  this  item 
Word— ID  of  menu  into  which  to  insert  item 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  InsertMItem2 (refDescriptor, 
menuItemTRef,    insertAfter,    menuNum) ; 

Word  refDescriptor,    insertAfter,    menuNum; 

Long  menuItemTRef; 

refDescriptor         Indicates  the  type  of  reference  stored  in  menuTRef  Valid  values  are: 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 

insertAfter  Specifies  ID  of  item  after  which  the  new  item  is  to  be  inserted.  In 

order  to  insert  the  new  item  at  the  top  of  the  menu,  set  this  field  to  0. 
To  insert  at  the  end,  set  this  field  to  $FFFF. 
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NewMenu2     $3£0F 

Allocates  space  for  a  menu  list  and  its  items.  This  call  accepts  a  menu  template  for  its 
input  specification. 


Par 

Stac 

ameters 

k  before  call 

Previous  contents 

Space 

Long— Space  for  result 

re/Descriptor 

Word— Defines  type  of  reference  in  menuTRef 

menuTRef 

Long — Reference  to  menu  template 

Stac 

k  after  call 
Previous  contents 

<— SP 

-  menuBarHandle 

Long — Handle  for  new  menu 

Em 
C 

)rs                  None 
exte 

Word 
Long 

<— SP 

m  pascal   Long  NewMenu2 (refDescriptor, 
menuTRef) ; 

refDescriptor; 
menuTRef; 

refDescriptor         Indicates  the  type  of  reference  stored  in  menuTRef  Valid  values  are: 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 
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NewMenuBar2     $430F 

Creates  a  default  menu  bar  with  no  menus.  This  call  accepts  a  menu  bar  template  for  its 
input  specification. 

The  upper-left  comer  of  the  default  menu  bar  matches  the  port,  and  is  as  wide  as  the 
screen.  The  bar  is  13  pixels  high. 

Note  that  passing  a  NIL  value  for  the  windowPtr  parameter  creates  a  menu  bar  that  is  not 
inside  a  window,  but  does  not  automatically  replace  the  current  menu  bar.  In  order  to 
create  a  new  system  menu  bar  and  make  it  current,  you  must  issue  the  following  tool  calls: 

NewMenuBar2 {) 

SetSysBar  /*  use  menuBarHandle  from  NewMenuBar2  */ 

SetMenuBar(NIL) 

Parameters 

Stack  before  call 


Previous  contents 


Space 


re/Descriptor 


-    menuBarTRef 


-     windowPtr     - 


Stack  after  call 


Long— Space  for  result 

Word— Defines  type  of  reference  in  menuBarTRef 

Long— Reference  to  menu  bar  template 

Long— Pointer  to  port  for  window;  NIL  for  system  menu  bar 
<— SP 


Previous  contents 


-  menuBarHandle 


Errors 
C 


None 


Long— Handle  for-new  menu  bar 
<— SP 


extern  pascal  Long  NewMenuBar2 (refDescriptor, 
menuBarTRef,  windowPtr) ; 
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Word      refDescriptor; 
Long      menuBarTRef ; 
Pointer   windowPtr; 

refDescriptor         Indicates  the  type  of  reference  stored  in  menuBarTRef.  Valid  values 
are: 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 
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PopUpMenuSelect     $3C0F 

Draws  highlighted  titles  and  handles  user  interaction  when  the  user  clicks  on  a  pop-up 
menu. 

You  specify  the  pop-up  with  the  handle  returned  by  NewMenu  or  NewMenu2. 


♦   Note:  The  system  draws  the  pop-up  menu  into  the  port  that  is  active  at  the  time  you 
issue  the  PopUpMenuSelect  call.  The  menu  is  constrained  by  the  intersection  of  the 
port  rectangle,  the  visible  region,  and  the  clip  region.  By  altering  any  of  these  you  can 
change  the  constraints  on  the  menu. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


selection 


currentLeft 


currentTop 


flag 


-    menuHandle   - 


Stack  after  call 


Word— Space  for  result  (Item  ID) 

Word— Item  ID  of  current  menu  selection 

Word— Global  coordinate  value  of  left  edge  of  pop-up  menu 

Word— Global  coordinate  value  of  top  of  current  selection 

Word— Flag  word  for  call 

Long— Menu  handle 

<— SP 


Previous  contents 


itemID 


Errors 


None 


Word— Item  ID  of  new  selection  (0  if  none) 
<— SP 
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C  extern  pascal  Word  PopUpMenuSelect (selection, 

currentLeft,  currentTop,  flag, 
menuHandle) ; 

Word      selection,  currentLeft,  currentTop,  flag; 
Long      menuHandle; 

selection  Defines  the  current  selection  in  the  menu.  Set  to  0  if  no  item  is 

currently  selected.  The  initial  value  is  the  default  value  for  the  menu, 
and  is  displayed  in  the  pop-up  rectangle  of  "unpopped"  menus.  You 
specify  an  item  by  its  ID,  that  is,  its  relative  position  within  the  array 
of  items  for  the  menu  (see  Chapter  37,  "Menu  Manager  Update,"  for 
information  on  the  layout  and  content  of  the  pop-up  menu  template). 
If  you  pass  an  invalid  item  ID  then  no  item  is  displayed  in  the  pop-up 
rectangle. 

currentLeft,  currentTop 

Define  the  left  edge  of  the  pop-up  and  the  top  of  the  current 
selection,  global  coordinates. 

flag  Flag  word  for  the  tool  call.  Bits  are  defined  as  follows: 

Reserved  bits  7-15     Must  be  set  to  0 

tyPe2  bit  6  Indicates  whether  pop-up  is  type  1  or  type2: 

0  -  Type  1  menu  (no  white  space  added) 

1  -  Type  2  menu  (white  space  added) 
Reserved                   bits  0-5      Must  be  set  to  0 

menuHandle         The  handle  of  the  pop-up  menu.  The  Menu  Manager  returned  this  value 
to  your  application  from  NewMenu  or  NewMenu2. 
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SetMenuTitle2     $400F 

Specifies  the  title  for  a  menu.  This  call  accepts  a  reference  to  the  title  string  that  can  be  a 
pointer,  handle,  or  resource  ID. 

Parameters 

Stack  before  call 


Previous  contents 


reJDescriptor 


HtleRef 


menuNum 


Stack  after  call 


Previous  contents 


Errors 
C 


None 


Word— Defines  type  of  reference  in  HtleRef 
Long— Reference  to  title  string  for  menu 
Word— ID  of  menu  to  receive  title 
<— SP 


<— SP 


extern  pascal  void  SetMenuTitle2 (refDescriptor, 
titleRef ,  menuNum) ; 


Word 
Long 


refDescriptor,  menuNum; 
menuItemTRef ; 


refDescriptor         Indicates  the  type  of  reference  stored  in  titleRef.  Valid  values  are: 


0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 
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SetMItem2     $4lOF 

Specifies  the  name  for  a  menu  item.  This  call  accepts  a  menu  item  template  for  its  input 
specification. 

Parameters 

Stack  before  call 


Previous  contents 


refDescriptor 


-  menuItemTRef  - 


menultem 


Stack  after  call 


Previous  contents 


Errors 
C 


None 


Word— Defines  type  of  reference  in  menuItemTRef 

Long— Reference  to  menu  item  template 

Word— ID  of  item  to  be  changed 
<— SP 


<— SP 


extern  pascal  void  SetMItem2 (refDescriptor, 
menuItemTRef,  menultem) ; 

Word      refDescriptor,  menultem; 
Long      menuItemTRef; 

re/Descriptor         Indicates  the  type  of  reference  stored  in  menuItemTRef.  Valid  values 
are: 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 

menultem  Specifies  the  menu  item  to  be  changed.  Note  that  you  can  change  the 

item  ID  by  specifying  a  different  item  number  in  the  menu  item 
template.  The  Menu  Manager  will  apply  the  item  ID  from  the  template 
to  the  item  to  be  changed. 
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SetMItemName2     $420F 

Specifies  the  name  of  a  menu  item  .  This  call  accepts  a  reference  to  a  title  string  that  can 
be  a  pointer,  handle,  or  resource  ID. 

Parameters 

Stack  before  call 


Previous  contents 


re/Descriptor 


titleRef 


menultem 


Stack  after  call 


Word— Defines  type  of  reference  in  titleRef 

Long— Reference  to  menu  item  title 

Word— ID  of  item  to  be  changed 
<— SP 


Previous  contents 


Errors 
C 


refDescriptor 


None 


<— SP 


extern  pascal  void  SetMItemName2 (refDescriptor, 
titleRef,  menultem) ; 

Word      refDescriptor,  menuNum; 
Long      titleRef; 

Indicates  the  type  of  reference  stored  in  titleRef.  Valid  values  are: 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 
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ShowMenuBar    $460F 

Reveals  the  system  menu  bar,  by  subtracting  the  menu  bar  from  the  desktop  region.  This 
call  also  resets  the  invisible  flag  for  the  menu  bar,  resets  scan  lines  2  through  9  (to 
correctly  display  the  colors  of  the  Apple  logo),  and  draws  the  menu.  Use  the 
HideMenuBar  call  to  make  the  menu  bar  invisible. 

Parameters 

Stack  before  call 


Previous  contents 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 
C 


None 


extern  pascal  void  ShowMenuBar ( ) 
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Chapter  38   MIDI  Tool  Set 


This  chapter  documents  the  MIDI  Tool  Set.  This  is  a  new  tool  set;  it  was 
not  documented  in  the  Apple  IIGS  Toolbox  Reference. 
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About  the  MIDI  Tool  Set 

The  Apple  IIGS  MIDI  Tool  Set  provides  a  software  interface  between  the  Apple  IIGS  and 
external  synthesizers  and  other  musical  equipment  that  accepts  the  Musical  Instrument 
Digital  Interface  (MIDI)  protocol.  The  MIDI  Tool  Set  has  the  following  key  attributes: 

■  Hardware  independence 

The  MIDI  Tool  Set  is  hardware-independent.  It  uses  a  separately  loaded  device  driver 
to  communicate  with  the  hardware  interface  that  connects  the  Apple  IIGS  to  an 
external  MIDI  device.  This  driver-based  design  frees  applications  from  referencing  the 
specifics  of  the  MIDI  hardware  interface.  Applications  that  use  the  MIDI  Tool  Set  can 
therefore  run  on  Apple  IIGS  systems  with  different  MIDI  interfaces. 

■  Interrupt-driven  operation 

The  MIDI  Tool  Set  is  interrupt-driven  and  can  transfer  MIDI  data  in  the  background 
while  other  tasks  take  place  in  the  foreground.  For  example,  it  is  possible  to  write  an 
application  that  enables  a  user  to  edit  MIDI  data  while  simultaneously  playing  a 
sequence.  MIDI  applications  that  use  the  tool  set  need  not  provide  interrupt  handlers 
since  they  are  provided  by  the  MIDI  Tool  Set. 

■  Accurate  clock 

The  MIDI  Tool  Set  provides  a  high-speed,  high-resolution  clock.  If -an  application 
needs  precise  timing,  it  can  use  the  MIDI  Tool  Set  clock  to  provide  time-stamps 
accurate  to  within  76  microseconds.  The  clock  uses  one  of  the  Digital  Oscillator 
Chip  (DOC)  generators  and  the  first  256  bytes  of  DOC  RAM.  When  the  clock  is  not  in 
use,  the  MIDI  Tool  Set  releases  the  DOC  generator  and  RAM.  See 
Chapter  47,  "Sound  Tool  Set  Update,"  for  more  information  about  the  Digital 
Oscillator  Chip. 

■  Fast  response 

The  tool  set  automatically  polls  incoming  MIDI  data,  and  receives  the  data  without 
loss  at  speeds  up  to  one  byte  per  320  microseconds—as  long  as  interrupts  are  never 
disabled  for  more  than  270  microseconds.  If  your  application  must  disable  interrupts 
for  longer  than  this  interval,  you  can  use  the  MidiinputPoii  vector  to  retrieve 
incoming  data  explicitly. 

■  Multiple  formats 

The  tool  set  supports  two  input  and  output  formats.  When  the  application  retrieves 
MIDI  data  in  raw  mode,  it  receives  the  data  bytes  exactly  as  they  appear  in  the  input 
stream,  but  with  length  and  time-stamp  data  added.  In  packet  mode,  the  MIDI  Tool 
Set  expects  to  receive  MIDI  data  packets,  but  will  perform  some  additional  cleanup 
to  make  those  packets  complete. 
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Error  checks 

The  MIDI  Tool  Set  provides  error-checking  and  reports  a  variety  of  error  conditions, 
including  reception  of  MIDI  packets  with  an  incorrect  number  of  data  bytes. 

Real-time  and  background  commands 

The  MIDI  Tool  Set  can  report  real-time  commands  to  an  application  immediately.  This 
feature  enables  the  application  to  process  real-time  commands  as  they  occur,  for 
interactive  control  of  musical  instruments. 

Intelligent  NoteOff  commands 

The  tool  sefs  NoteOff  commands  can  turn  off  all  notes  that  are  playing  or  only  those  it 
has  turned  on.  They  can  do  this  on  all  channels  or  only  on  specified  channels. 

Variable  clock  frequency 

You  can  change  the  time  base  for  MIDI  timestamps,  thereby  varying  the  tempo  of 
played  data  (see  the  description  of  the  miSetFreq  function  of  the  Midiciock  tool 
call  later  in  this  chapter  for  more  information). 

User  definable  service  routines 

You  can  enhance  the  functionality  provided  by  the  MIDI  Tool  Set  by  providing  your 
own  service  routines.  The  MIDI  Tool  Set  calls  these  routines  under  a  variety  of  defined 
circumstances.  See  "MIDI  Tool  Set  service  routines"  later  in  this  chapter  for  more 
information. 


♦   Note:  The  Note  Synthesizer,  the  Note  Sequencer,  and  the  MIDI  Tool  Set  refer  to  the 
software  tools  provided  with  the  Apple  IIGS,  not  to  any  separate  instrument  or 
device.  The  MIDI  tools  are  software  tools  for  use  in  controlling  external  instruments, 
which  may  be  connected  through  a  MIDI  interface  device. 
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Using  the  MIDI  Tool  Set 

This  section  describes  the  basic  steps  involved  in  using  the  MIDI  Tool  Set  to  interact  with 
external  musical  instruments.  Following  the  initial  overview  discussion  are  several  code 
examples,  demonstrating  techniques  for  performing  many  key  MIDI  Tools  functions. 

Figure  38-1  illustrates  some  of  the  relationships  between  a  typical  MIDI  application,  the 
MIDI  Tool  Set,  MIDI  device  drivers,  and  a  MIDI  interface  card. 
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Figure  38-1      MIDI  application  environment 
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Before  using  the  MIDI  Tool  Set,  you  must  install  the  tool  set  and  its  associated  drivers 
using  the  Installer  utility. 
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To  use  the  MIDI  Tool  Set,  you  must  first  start  it  up  with  the  Midistartup  call.  Then  you 
must  load  a  MIDI  device  driver  by  using  the  MidiDevice  call.  The  tool  set  loads  the 
driver  separately  so  that  its  operation  is  independent  of  the  particular  MIDI  interface  that 
connects  the  Apple  IIGS  to  the  external  MIDI  instrument. 

MIDI  device  drivers  are  normally  found  in  the  VSYSTEM/DRIVERS  directory,  and  end  with 
the  suffix  .MIDI.  Apple  currently  supplies  the  APPLE.MIDI  and  CARD6850.MIDI  drivers; 
the  first  driver  supports  the  Apple  MIDI  Interface,  and  the  second  supports  plug-in  6850- 
based  Asynchronous  Communications  Interface  Adapter  (ACIA)  cards. 

After  the  application  loads  the  MIDI  device  driver,  it  must  make  the  Midicontroi  call 

to  allocate  input  and  output  buffers  for  MidiReadPacket  and  MidiWritePacket 
calls.  Note  that  if  the  application  never  calls  MidiReadPacket,  it  need  not  allocate  an 
input  buffer,  and  if  it  never  calls  MidiWritePacket,  it  need  not  allocate  an  output 
buffer. 

The  MIDI  Tool  Set  is  now  ready  to  send  or  receive  MIDI  data.  However,  the  application 
must  explicitly  start  the  MIDI  input  and  output  processes,  using  the  appropriate  options 

Of  the  MidiControl  tool  Call. 

The  application  can  start  or  stop  MIDI  data  transfer  at  any  time.  Once  started,  the  input 
and  output  processes  continue  without  intervention  until  stopped  by  the  application. 
They  run  in  the  background  so  that  other  processes,  such  as  interaction  with  the  user,  can 
run  unimpeded  in  the  foreground.  The  tool  set  enables  the  programmer  to  switch  the 
processes  on  or  off  at  any  time  because  MIDI  data  transfer  incurs  considerable  processor 
overhead,  and  a  programmer  might  want  to  disable  it  under  some  circumstances  to 
improve  the  application's  performance  on  other  tasks. 

The  MIDI  input  process  fills  the  MIDI  Tool  Sef  s  input  buffer  with  data  packets  as  they 
arrive.  The  application  must  periodically  retrieve  the  data  from  the  buffer  by  making  calls 
to  MidiReadPacket.  Similarly,  the  MIDI  output  process  transmits  the  data  placed  in 
the  tool  sefs  output  buffer  by  application  with  calls  to  MidiWritePacket.  The  Apple 
IIGS  can  simultaneously  send  and  receive  MIDI  data  packets. 

When  you  use  the  Midiciock  call  to  start  the  MIDI  Tool  Sefs  clock,  the  tool  set  begins 
stamping  each  data  packet  with  a  time  value  it  retrieves  from  its  clock  process.  This 
clock  is  actually  a  DOC  generator  that  the  MDI  Tool  Set  allocates  with  the  Note 
Synthesizer  AiiocGen  call.  Start  the  MIDI  clock  before  starting  the  input  process, 
because  the  Midiciock  function  disables  interrupts  long  enough  to  interfere  with 
correct  reception  of  MIDI  data. 
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The  clock  is  very  fast;  a  tick  occurs  every  76  microseconds  at  the  default  settings.  MIDI 
data  packets  receive  a  time-stamp  consisting  of  the  value  of  the  clock  when  they  are 
received.  MidiwritePacket  receives  a  packet  with  a  time-stamp  attached  and  writes 
it  to  the  output  buffer,  and  the  MIDI  Tool  Set  transfers  the  packet  only  when  the  current 
value  of  the  clock  is  greater  than  the  output  data's  time-stamp. 

If  the  clock  is  stopped,  MIDI  input  data  receive  time-stamps  equal  to  the  value  of  the 
stopped  clock,  and  only  MIDI  data  with  time-stamps  less  than  the  value  of  the  stopped 
clock  can  be  sent. 

If  you  want  to  read  and  write  MIDI  packets  in  real  time,  in  response  to  user  events,  you  do 
not  need  the  MIDI  clock. 

You  can  start  or  stop  the  MIDI  clock  or  the  input  and  output  processes  at  any  time,  so 
that  you  can  budget  processor  resources  intelligently.  The  input,  output,  and  clock 
processes  consume  a  great  deal  of  processor  time,  and  so  limit  the  processing  power 
available  to  tasks  that  execute  during  their  operation. 


Tool  dependencies 

The  MIDI  Tool  Set  uses  Note  Synthesizer  calls  to  allocate  a  DOC  generator  for  its  clock.  If 
your  application  does  not  use  the  MIDI  Tool  Set  clock,  you  need  not  start  up  the  Note 
Synthesizer  to  use  the  MIDI  Tool  Set.  If  your  application  is  not  using  the  MIDI  Tool  Set 
clock  or  MidiinputPoii,  then  it  can  start  up  and  shut  down  the  Note  Synthesizer  as 
needed,  but  the  Note  Synthesizer  must  be  started  up  if  you  use  the  MIDI  clock  or  the 

MidiinputPoii  vector. 

The  Sound  Tools  must  be  started  to  use  the  MIDI  tools. 

Refer  to  Chapter  51,  "Tool  Locator  Update,"  for  information  about  the  specific  version 
requirements  the  MIDI  Tool  Set  has  for  other  tool  sets. 


MIDI  packet  format 


MIDI  data  sent  and  received  using  the  MIDI  Tool  Set  must  always  be  formatted  into  valid 
MIDI  Tool  Set  packets.  The  tool  set  handles  this  for  incoming  data;  your  application  must 
format  outgoing  data  according  to  the  packet  layout  described  in  this  section. 
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The  first  2  bytes  of  a  packet  contain  a  byte  count  of  the  MIDI  data  in  the  packet,  plus  the 
4-byte  time-stamp.  The  next  4  bytes  are  the  time-stamp,  and  are  equal  to  the  value  of  the 
MIDI  clock  at  the  time  the  packet  was  received.  The  remaining  bytes  are  the  actual  MIDI 
data: 


$00 
$02 


length 


Word— Packet  length  (excluding  length ) 


timestamp  :  4  Bytes— MIDI  time-stamp 

$06  I  I 

:  MiDiData  \  Array— MIDI  data  (variable  length) 


A  NoteOn  command  might  look  like  this  (in  hex  notation): 

0700  24630300    90405C 

The  first  2  bytes  are  the  length  in  bytes  of  the  MIDI  data  packet  plus  the  4-byte 
time-stamp.  In  this  case  the  MIDI  packet  is  3  bytes,  so  the  length  value  is  7.  The  next  4 
bytes  contain  the  time-stamp,  and  the  MIDI  data  follow. 

The  result  of  a  MidiReadPacket  call  on  this  packet  is  9— the  7  bytes  counted  in  the 
length  word  plus  the  2  bytes  of  the  length  word  itself. 

If  the  current  input  mode  is  MIDI  packet  mode,  the  first  byte  of  the  MIDI  data  is  always  a 
MIDI  status  byte.  If  a  received  MIDI  packet  does  not  contain  a  valid  status  byte,  the 
MIDI  Tool  Set  inserts  the  current  status  at  the  beginning  of  the  packet. 
MidiReadPacket  never  returns  real-time  commands  in  packet  mode;  they  are  always 
passed  to  the  real-time  command  routine  installed  by  Midicontroi.  See  "MIDI  Tool  Set 
service  routines"  later  in  this  chapter  for  more  information. 

In  raw  mode  the  MIDI  data  are  returned  to  the  application  just  as  they  are  received  from 
the  MIDI  interface.  The  MIDI  protocol  allows  MIDI  devices  to  omit  the  status  byte  unless 
it  has  changed  from  its  last  value.  The  status  byte  may  appear  anywhere  in  the  stream 
because  it  may  be  received  only  when  it  changes.  MIDI  devices  may  also  omit  the  $F7 
value  at  the  end  of  a  MIDI  System  Exclusive  command;  the  $F7  value  always  appears  at  the 
end  of  a  System  Exclusive  command  in  packet  mode,  but  not  necessarily  in  raw  mode. 
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In  raw  mode,  the  maximum  number  of  MIDI  data  bytes  that  MidiReadPacket  passes  to 
the  application  is  4.  Therefore,  the  longest  packet  it  can  pass  is  10  bytes  in  length— 2 
length  bytes,  4  time-stamp  bytes,  and  4  MIDI  data  bytes.  In  packet  mode,  System 
Exclusive  packets  may  be  of  any  length. 

MidiReadPacket  also  returns  real-time  commands  in  raw  mode  unless  a  real-time  vector 
is  installed  See  "MidiControi"  later  in  this  chapter  for  more  information. 


MIDI  Tool  Set  service  routines 

Your  program  can  contain  service  routines  that  the  MIDI  Tool  Set  will  invoke  under  certain 
defined  circumstances.  By  providing  these  service  routines,  you  can  tailor  the 
functionality  of  the  MIDI  Tool  Set  to  fit  your  particular  needs.  The  MIDI  Tool  Set  calls 
these  routines  under  the  following  circumstances 


Real-time  error  routine 


Input  data  routine 


Real-time  command  routine        Called  when  the  MIDI  Tool  Set  receives  a  MIDI  real-time 

command.  You  set  the  vector  to  this  routine  with  the 
miSetRTVec  function  of  the  MidiControi  tool  call. 

Called  when  the  MIDI  Tool  Set  encounters  an  error 
during  real-time  processing.  You  set  the  vector  to  this 
routine  with  the  misetErrVec  function  of  the 
MidiControi  tool  call. 

Called  by  the  MIDI  Tool  Set  to  handle  MIDI  data 
received  during  processing  of  an  mistartinput 
function  request.  You  set  the  vector  to  this  routine 
when  you  issue  the  mistartinput  function  of  the 

MidiControi  tool  Call. 

Called  by  the  MIDI  Tool  Set  to  obtain  data  to  send 
during  processing  of  an  mistartoutput  function 
request.  You  set  the  vector  to  this  routine  when  you 
issue  the  mistartoutput  function  of  the 
MidiControi  tool  call. 

The  following  sections  discuss  each  of  these  service  routines  in  more  detail. 


Output  data  routine 
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Real-time  command  routine 

When  the  MIDI  Tool  Set  receives  MIDI  real-time  commands,  it  calls  this  service  routine. 
The  service  routine  must  not  enable  interrupts,  and  if  it  runs  for  longer  than  300 
microseconds,  it  must  call  the  MIDI  polling  vector  at  least  every  270  microseconds.  The 
only  MIDI  calls  that  the  service  routine  should  make  are  MidiReadPacket  and 
MidiWritePacket. 

Real-time  MIDI  data  are  passed  to  the  service  routine  in  the  low-order  byte  of  a  word  on 
the  stack  above  the  rtl  address.  This  word  must  remain  on  the  stack.  When  the  service 
routine  is  called,  the  data  bank  register  is  set  to  the  value  it  had  when  Midistartup  was 
called,  but  the  direct-page  register  points  to  one  of  the  MIDI  Tool  Set's  direct  pages  and 
must  be  preserved. 

You  set  the  vector  to  this  routine  with  the  misetRTVec  function  of  the  Midicontroi 
tool  call. 

Parameters 

Stack  before  call 


Previous  contents 


MDIData 


-   returnAddress  - 


Word— Low-order  byte  contains  MIDI  real-time  data 
3  Bytes— rtl  address 

<— SP 


Stack  after  call 


Previous  contents 


MDIData 


-   returnAddress  - 


Word— Low-order  byte  contains  MIDI  real-time  data 
3  Bytes— rtl  address 
<— SP 
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Real-time  error  routine 

The  MIDI  Tool  Set  calls  this  routine  in  the  event  of  a  MIDI  real-time  error.  This  service 
routine  must  not  enable  interrupts.  If  it  executes  for  longer  than  300  microseconds,  it 
must  call  the  MIDI  polling  vector  at  least  every  270  microseconds.  It  can  call 
MidiWritePacket  and  MidiReadPacket,  but  no  Other  MIDI  tool  calls. 

The  error  is  passed  to  the  service  routine  in  a  word  on  the  stack  above  the  rtl  address. 
This  word  must  remain  on  the  stack.  When  the  service  routine  is  called,  the  data  bank 
register  is  set  to  the  value  it  had  when  Midi  startup  was  called,  but  the  direct  page 
register  points  to  one  of  the  MIDI  Tool  Set's  direct  pages  and  must  be  preserved.  When 
the  MIDI  Tool  Set  invokes  this  routine,  there  is  very  little  space  left  on  the  stack. 

You  set  the  vector  to  this  routine  with  the  miSetErrvec  function  of  the  Midicontroi 
tool  call. 


The  service  routine  may  receive  the  following  error  codes: 


$200^ 

l         miClockErr 

$2084 

miDevNoConnect 

Parameters 

Stack  before  call 

Previous  contents 

MIDIError 

Word— Error  code 

-  returnAddress  - 

3  Bytes— rtl  address 

<— SP 

Stack  after  call 

Previous  contents 

MIDIError 

Word — Error  code 

-   returnAddress   - 

3  Bytes — rtl  address 

<— SP 

MIDI  clock  wrapped  to  0. 
No  connection  to  MIDI 
interface. 
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Input  data  routine 

The  MIDI  Tool  Set  calls  this  routine  during  processing  of  the  mi  start  input  function  of 
the  Midi  control  tool  call  when  the  first  packet  is  available  in  a  previously  empty  input 
buffer.  The  service  routine  must  not  enable  interrupts,  and  if  it  runs  for  longer  than  300 
microseconds,  it  must  call  MidiinputPoii  at  least  every  270  microseconds.  The  only 
MIDI  calls  that  the  service  routine  should  make  are  MidiReadPacket  and 
MidiWritePacket. 

When  the  service  routine  is  called,  the  data  bank  register  is  set  to  the  value  it  had  when 
Midistartup  was  called,  but  the  direct  page  register  points  to  one  of  the  MIDI  Tool 
Sef  s  direct  pages  and  must  be  preserved.  The  system  will  call  the  service  routine 
immediately  if  a  complete  MIDI  packet  is  available  in  the  input  buffer  when  the 
mistartinput  function  of  the  MidiControi  tool  call  is  made. 

You  set  the  vector  to  this  routine  when  you  issue  the  mistartinput  function  of  the 
MidiControi  tool  call. 

Parameters 

Stack  before  call 


Previous  contents 


-  returnAddress  - 


3  Bytes— rtl  address 
<— SP 


Stack  after  call 


Previous  contents 


-  returnAddress  - 


3  Bytes— rtl  address 
<— SP 
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Output  data  routine 

The  MIDI  Tool  Set  calls  this  routine  during  processing  of  the  mistartoutput  function 
of  the  Midicontroi  tool  call  when  the  output  buffer  becomes  completely  empty.  The 
service  routine  must  not  enable  interrupts,  and  if  it  runs  for  longer  than  300  microseconds, 
it  must  call  the  MIDI  polling  vector  at  least  every  270  microseconds.  The  only  MIDI  calls 
that  the  service  routine  should  make  are  MidiReadPacket  and  MidiwritePacket. 

When  the  service  routine  is  called,  the  data  bank  register  is  set  to  the  value  it  had  when 
Midi  st  art  up  was  called,  but  the  direct  page  register  points  to  one  of  the  MIDI  Tool 
Sef  s  direct  pages  and  must  be  preserved. 

You  set  the  vector  to  this  routine  when  you  issue  the  mistartoutput  function  of  the 

MidiControl  tool  Call. 


Parameters 

Stack  before  call 


Previous  contents 


-   returnAddress  - 


3  Bytes— rtl  address 
<— SP 


Stack  after  call 


Previous  contents 


-   returnAddress  - 


3  Bytes— rtl  address 
<— SP 
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Starting  up  the  MIDI  Tool  Set 

The  Midistartup  call  takes  as  arguments  a  word  containing  the  Memory  Manager  ID 
number  of  the  application  that  is  starting  up  the  tools,  and  a  word  containing  the  address 
of  a  three-page  memory  block  in  bank  zero.  The  three-page  block  is  used  as  the  MIDI 
Tool  Set's  direct-page  area,  and  it  must  be  aligned  on  a  page  boundary. 


/* 


StartupTools () 

Starts  up  the  MIDI  Tool  Set  and  all  of  the  tools  it 

requires.   For  readability,  this  subroutine  is  presented 

without  the  error-checking  that  would  normally  be  performed 
after  each  tool  is  started  (call?) . 


'/ 


/*  direct  page  use  */ 

#define  DPForSound  0x0000 

#define  DPForMidi  0x0100 

#define  DPForEventMgr  0x0400 

#define  TotalDP  0x0500 

static  word  AppID; 

void 
StartupTools () 

{ 

static  struct  { 

word  NumberOf Tools; 
word  Table [5*2] ; 
}  ToolTable  =  { 
5, 

1,  0x0101, 

2,  0x0101, 
8,   miSTVer, 
25,  miNSVer, 
miToolNum,  0x0000 

}; 

MiDriverlnfo  Driverlnfo; 

MiBuflnfo  InBufInfo,OutBufInfo; 


/*  needs  1  */ 

/*  needs  3  */ 

/*  needs  1  */ 

/*  total  direct  page  use  */ 

/*  Apps  Memory  Manager  ID  */ 


/*  number  of  tools  in  list  */ 

/*  Tool  Locator  */ 

/*  Memory  Manager  */ 

/*  Sound  Tools  */ 

/*  Note  Synthesizer  */ 

/*  Midi  Tool  Set  */ 

/*  device  driver  info  */ 

/*  I/O  buffer  information  */ 
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handle  ZeroPageHandle; 
ptr  ZeroPagePtr; 


TLStartUpO;  /*  Tool  Locator  startup  */ 

AppID  =  MMStartUpf);  /*  Memory  Manager  startup  */ 

/*  allocate  direct  pages  for  tools  */ 
ZeroPageHandle  =  NewHandle ( (long)  TotalDP, 

(word)  AppID, 

(word)  attrBank  |  attrPage  I  attrFixed 
I  attrLocked, 

(long)  0); 
ZeroPagePtr  =  *ZeroPageHandle; 

EMStartUp( (word) (ZeroPagePtr  +  DPForEventMgr) ,  (word)  0, 
(word)  0, 
(word)  640, 
(word)  0, 
(word)  200, 
(word)  AppID  )  ; 

LoadTools (SToolTable) ;  /*  load  RAM-based  tools  */ 

SoundStartUp ( (word) (ZeroPagePtr  +  DPForSound) ) ; 

NSStartUp(0,  0L) ; 

MidiStartUp (AppID,  (word) (ZeroPagePtr  +  DPForMidi) ) ; 

/*  load  device  driver  */ 
Driverlnfo.slot  =2;  /*  use  the  modem  port  */ 

Driverlnfo. external  =0;  /*  internal  slot  */ 

strcpy (Driverlnfo.file,  "\p*/system/ drivers/apple. midi") ; 
MidiDevice (miLoadDrvr,  &DriverInf o) ; 
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I*   allocate  input  and  output  buffers  */ 


InBuflnfo.bufSize  =  0; 
InBuf Info. address  =  0; 


MidiControl (miSetlnBuf ,  filnBuf Inf o) 
OutBuflnfo.bufSize  =  0; 
OutBuf Info. address  =  0; 


/* 
/* 


/* 
/* 


MidiControl (miSetOutBuf ,  &OutBuf Inf o) ; 
/*  end  of  StartupTools ()  */ 


default  size  */ 
MIDI  Tool  Set  will 
allocate  the  buffer  and 
set  its  actual  address  */ 

default  size  */ 
MIDI  Tool  Set  will 
allocate  the  buffer  and 
set  its  actual  address  */ 


Reading  time-stamped  MIDI  data 

This  example  shows  a  simple  method  of  recording  time-stamped  MIDI  data  as  it  is 
received.  The  example  records  incoming  data  until  any  key  is  depressed  or  until  the  MIDI 
Tool  Set's  internal  data  buffer  is  full,  whichever  comes  first.  The  routine's  data  buffer 
should  not  be  confused  with  the  MIDI  Tool  Sef  s  input  buffer,  which  you  allocate  for  MIDI 
data  by  using  the  MidiControl  call. 

/* 

*  RecordMIDI ( ) 
* 

*  Record  incoming  MIDI  data  with  time  stamps  into  the 

*  global  buffer  "AppMIDIBuffer"  until  the  buffer  is 

*  full  or  the  user  presses  the  mouse  button. 
*/ 

fdefine  BufSize         (20  *  1024) 
char  SeqBuffer [BufSize] ; 
int  Buf Index  =  0; 
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void 
RecordMIDI () 

{ 

int  PacketSize; 


MidiControl (miFlushlnput,  OL) ; 

MidiClock (miSetFreq,  OL) ; 

MidiClock (miSetClock,  OL) ; 
MidiClock (miStartClock,  OL) ; 
MidiControl (miSetlnMode, 

(long)miPacketMode) ; 
MidiControl (miStartlnput,  OL)  ; 

Buf Index  =  0; 


/*  size  of  packet  read  */ 


/*  discard  contents 
of  input  buffer  */ 

/*  set  clock  to 

default  frequency  */ 

/*  clear  the  clock  */ 

/*  start  the  clock  */ 

/*  set  MIDI  input  mode  */ 
/*  start  MIDI  input  */ 


/*  until  presses  mouse  */ 


while  (  Button (0)  ==  0  ) 

{ 

PacketSize  =  MidiReadPacket (SeqBuf fer+Buf Index, 

Buf Size-Buflndex) ; 
if  (  toolErr) 


{ 


if  (_toolErr  ==  miArrayErr) 
i 


break; 


/*  our  buffer  is  full  */ 


} 
else 

{ 
} 


printf ("MIDI  error  $%4 .4X\n",_toolErr) ; 


} 

else 
{ 

} 


Buflndex  +=  PacketSize; 


Chapter  38    MIDI  Tool  Set     38-17 


Apple  IIGS  Toolbox  Reference,  Volume  3  Beta  Draft  30  August  1989 


/*   stop  recording  */ 

MidiControl (mistoplnput,  OL)  ;        /*  stop  MIDI  input  */ 

MidiClock(miStopClock,  OL) ;         /*  stop  the  clock  */ 

/*  show  user  recording  statistics  */ 

printf ("Bytes  recorded:  %d\n",Buf Index)  ; 
printf ("Maximum  bytes  buffered:  %ld\n", 
Midilnfo (miMaxInChars) ) ; 
}     /*  end  of  RecordMIDIO  */ 

This  example  is  a  simple  subroutine  that  continuously  plays  previously  recorded  time-stamped  MIDI 
data  until  the  user  presses  any  key. 

/* 

*  PlayMIDK) 
* 

*  This  routine  repeatedly  plays  the  MIDI  data  that  was 

*  previously  recorded  and  stored  into  the  global  buffer 

*  "SeqBuffer"  until  the  user  presses  the  mouse  button. 
*/ 

void 
PlayMIDI () 

{ 

long  FirstTime; 
int  Playlndex; 

if  (Buf Index  ==  0) 
{ 

printf ("You  must  record  or  load  MIDI  data  first\n"); 

return; 
} 

/*  find  the  first  time  stamp  in  the  sequence  and  subtract 

a  little  */ 

FirstTime  =  * ( (long  *)  (SeqBuf fer+2) )  ; 

if  (FirstTime  >  0x200) 

FirstTime  -=  0x200; 
else 

FirstTime  =  0; 
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MidiControl (miFlushOutput, (long) (OxFFFF  «  16)); 

/*  empty  output  buffer  */ 
MidiClock(miSetClock,FirstTime) ;     /*  set  clock  before 

first  time  stamp*/ 
MidiClock (miStartClock, OL) ;         /*  start  clock  */ 
MidiControl (miSetOutMode,  (long)miPacketMode) ; 

/*  set  output  mode  */ 
MidiControl (miStartOutput, OL) ;      /*  start  output  */ 
Playlndex  =  0; 


/*  Until  presses  mouse  */ 


/*  Repeatedly  play  song  */ 
while  (  Button (0)  ==  0  ) 
{ 

Playlndex  +=  MidiWritePacket (SeqBuf fer  +  Playlndex); 

/*  write  next  packet  */ 

if  (Playlndex  ==  Buf Index)     /*  Time  to  repeat?  */ 


{ 


while  (  Button (0)  ==  0  &&  Midilnf o (miOutputChars) ) 

;  /*  wait  for  the  song  to  end  */ 

if  (Button(O)  ||  ILoopPlayback) 

break; 
MidiClock (miSetClock, FirstTime) ; 

/*  restart  clock  */ 
Playlndex  =  0; 


MidiControl (miFlushOutput, OxlOL) ; 


MidiClock (miStopClock, OL) ; 
MidiControl (miStopOutput, OL) ; 
/*  end  of  PlayMIDIO  */ 


/*  flush  output  buffer 

&  turn  all  notes  off  */ 
/*  stop  the  clock  */ 
/*  stop  output  */ 
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Fast  access  to  MIDI  Tool  Set  routines 

Because  of  the  tight  timing  requirements  of  MIDI  processing,  there  are  many  time-critical 
situations  in  which  the  overhead  of  a  tool  call  can  be  problematic.  When  you  need  to  save 
as  much  time  as  possible,  you  may  want  to  call  MIDI  Tool  Set  routines  directly  and  avoid 
the  time  needed  to  make  a  tool  call.  The  following  example  demonstrates  how  to  do  this 
in  65816  assembly  language.  This  example  can  save  approximately  85  microseconds  per 
call.  This  time  saving  can  be  very  helpful  in  an  application  that  makes  numerous  calls  to 
MidiReadPacket  andMidiWritePacket. 


look  up  the  address  of  MidiWritePacket  (as  an  example) 

pushlong  #0  ;  space  for  result 

pushword  #0  ;  system  tool 

pushword  #$0E20      ;  tool  and  function  number 

_GetFuncPtr 

pla 

sta  MidiWriteAddr    ;  save  the  address 

pla 

sta  MidiWriteAddr+2 
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;    do  this  instead  of  _MidiWritePacket 

r 

jsl  MidiWriteGlue 


IMPORTANT  NOTE:  The  variable  "MidiDP2"  must  contain  the 
address  of  the  second  page  of  bank  zero  memory  allocated  for 
the  MIDI  Tool  Set's  direct  page.  If  MidiStartUp  is  given 
a  starting  address  of  X,  then  MidiDP2  =  X  +  $100. 


MidiWriteGlue   jsl  MidiWriteGluel 

rtl 
MidiWriteGluel  Ida  MidiWriteAddr+1 
pha 
phb 

Ida  MidiWriteAddr 
sta  l,s 
Ida  MidiDP2 


GlueReturn      rtl 
MidiWriteAddr   ds  4 


push  an  extra  RTL 
address 

;  simulate  a  Tool  call 
;  to  MidiWritePacket 


the  A  register  must 
contain  the  address  of 
the  MIDI  Tool 
Set's  direct  page  address 
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MIDI  application  considerations 

This  section  contains  advice  on  a  number  of  topics,  and  is  intended  to  help  you  create 
more  satisfying  MIDI  applications. 

MIDI  and  AppleTalk 

The  MIDI  Tool  Set  is  not  designed  to  operate  with  AppleTalk®  enabled.  The  Apple  IIGS  is 
not  fast  enough  to  process  both  AppleTalk  interrupts  and  MIDI  interrupts  simultaneously. 
If  an  application  that  uses  the  MIDI  Tool  Set  runs  with  AppleTalk  enabled,  you  should 
expect  occasional  MIDI  input  errors  and  output  delays.  For  most  programs,  even  one 
MIDI  error  is  difficult  to  handle,  so  you  should  probably  recommend  that  applications 
that  use  the  MIDI  Tool  Set  not  be  used  with  AppleTalk  enabled. 

Disabling  interrupts 

Several  tool  calls  that  disable  interrupts  can  cause  loss  of  MIDI  data.  These  include  calls 
that  access  the  disk  drives,  Event  Manager  calls,  and  Dialog  Manager  calls. 

The  rate  of  MIDI  data  transfer  leaves  little  margin  for  error  in  the  MIDI  Tool  Set's 
operation.  The  rate  at  which  the  tool  set  must  retrieve  MIDI  data  places  great  demands  on 
the  system's  computational  resources.  If  possible,  an  application  should  avoid  disabling 
interrupts  while  reading  MIDI  data.  If  a  program  must  disable  interrupts  while  reading 
MIDI  data,  it  should  not  do  so  for  longer  than  270  microseconds. 

In  cases  where  compliance  with  these  restrictions  is  impossible,  you  can  use  the 
MidiinputPoii  vector.  This  vector  is  provided  for  those  applications  that  must 
disable  interrupts  for  dangerously  long  periods.  To  call  MidiinputPoii,  execute  a  jsl 
to  $E101B2.  If  the  MIDI  Tool  Set  has  not  been  started  up,  or  if  the  MIDI  input  process  has 
not  been  started,  the  vector  will  return  immediately.  Any  MIDI  data  that  were  present  on 
the  call  to  the  vector  will  appear  in  the  input  buffer  that  you  allocated  with 

MidiControl. 

♦   Note:  If  you  need  the  values  of  the  A,  X,  and  Y  registers,  you  must  save  them  yourself 
before  calling  the  vector.  The  direct-page  and  data  bank  registers  are  preserved. 
MidiinputPoii  must  be  called  only  in  full  native  mode. 
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A  Warning         Do  not  call  MidiinputPoii  before  loading  the  MIDI  Tool  Set  in  a 
system  with  a  Sound  Tool  Set  version  earlier  than  2.3  or  system 
software  earlier  than  4.0.  Doing  so  will  cause  a  system  failure.  ▲ 

If  you  use  the  MidiinputPoii  vector,  you  must  ensure  that  it  is  called  at  least  every  270 
microseconds,  or  MIDI  data  may  be  lost.  A  call  to  the  vector  when  no  data  are  present 
returns  in  from  8  to  30  microseconds,  and  when  data  are  present  the  vector  can  take  up  to 
450  microseconds,  at  150  microseconds  per  character  read. 

You  can  call  MidiReadPacket  and  MidiwritePacket  inside  interrupt-service 
routines,  because  they  perform  polling  automatically.  Other  tool  sets  do  not  perform 
MIDI  polling,  so  MIDI  applications  should  not  make  calls  to  other  tool  sets  in  interrupt- 
service  routines. 

A  Warning         Do  not  make  MIDI  Tool  Set  calls  other  than  MidiReadPacket  and 
MidiwritePacket  from  interrupt-service  routines.  Doing  so  can 
cause  unpredictable  system  failure.  ▲ 

Whenever  possible,  you  should  use  MIDI  interface  cards  that  support  MIDI  data 
buffering.  By  storing  some  received  data,  these  cards  relieve  the  time  constraints  on  your 
application. 

MIDI  and  other  sound-related  tool  sets 

If  you  use  the  recommended  versions  of  the  Note  Synthesizer,  Note  Sequencer,  and 
Sound  Tool  Set  (see  Chapter  51,  "Tool  Locator  Update,"  for  details),  these  tool  sets  are 
fully  compatible  with  the  MIDI  Tool  Set  and  do  not  cause  MIDI  data  losses.  It  is  possible 
to  write  programs  that  use  the  Note  Sequencer  to  play  notes  on  the  internal  voices  of  the 
Apple  IIGS  and  on  an  external  MIDI  synthesizer  while  simultaneously  accepting  MIDI  input 
from  an  external  keyboard  and  translating  it  to  Note  Synthesizer  commands  to  play  the 
notes. 

The  MIDI  clock 

This  section  discusses  the  technique  currently  used  to  generate  MIDI  time-stamps.  Note 
that  this  technique  may  not  be  used  on  future  Apple  IIGS  machines.  Any  application  that 
employs  a  similar  technique  to  implement  timing  may  be  incompatible  with  future 
systems. 
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Properly  time-stamping  MIDI  input  data  requires  a  clock  with  resolution  better  than  one 
millisecond.  When  a  long  stream  of  MIDI  data  is  received  in  a  short  time  period  (such  as 
when  the  user  plays  a  large  chord  on  a  MIDI  keyboard),  each  note  must  be  accurately  time- 
stamped.  However,  the  Apple  IIGS  cannot  process  interrupts  quickly  enough  to  satisfy 
this  requirement. 

To  provide  a  reasonable  clock  resolution,  the  Apple  IIGS  MIDI  time-stamp  is 
implemented  using  one  of  the  system's  DOC  generators.  The  MIDI  tool  set  loads  the  DOC 
with  a  256-byte  waveform  consisting  of  consecutive  values  from  $01  to  $FF  (followed  by 
an  additional  byte  of  $FF),  and  sets  the  DOC  to  play  this  waveform  at  zero  volume.  When 
a  MIDI  character  is  received,  the  time-stamping  routine  uses  the  value  from  this  DOC  for 
the  low-order  byte  of  the  time-stamp.  The  system  obtains  the  high-order  3  bytes  from  a 
counter  that  is  incremented  each  time  the  DOC  cycles  through  its  waveform  (once  every 
19.45  milliseconds  at  the  default  clock  rate).  This  technique  reduces  the  system  interrupt 
load  to  a  manageable  level  while  also  providing  sufficiently  fine  clock  resolution  to 
correcdy  process  MIDI  data. 

Because  the  MIDI  clock  is  actually  a  DOC  generator,  you  cannot  use  that  generator  while 
the  clock  is  running;  under  these  circumstances,  only  13  generators  are  available  for  general 
use.  The  clock  also  uses  the  first  256  bytes  of  DOC  RAM  for  its  waveform,  so  running  the 
clock  reduces  the  memory  available  for  application  waveforms.  While  the  clock  is  running 
you  must  not  use  the  Sound  Tool  Set's  free-form  synthesizer  (the  FFStartsound  call). 
The  frequency  and  duration  of  Sound  Tool  Set  interrupts  also  interferes  with  the  MIDI 
Tool  Set's  ability  to  perform  its  services  often  enough  to  prevent  data  loss. 

Input  and  output  buffer  sizing 

You  should  adjust  the  MIDI  input  buffer  size  for  the  amount  of  data  you  can  expect  to 
receive  before  the  application  processes  it.  Any  process  that  competes  with  the 
application  for  processor  time,  such  as  Note  Synthesizer  calls  to  play  complex  envelopes, 
reduces  the  frequency  at  which  the  application  can  call  MidiReadPacket  and  process 
the  data  in  the  input  buffer.  If  the  input  buffer  fills  before  it  can  be  processed,  data  will 
be  lost.  Complex  applications  that  use  time-consuming  tool  calls  therefore  require  large 
input  buffers. 

You  can  estimate  the  size  of  the  needed  input  buffer  from  the  size  of  the  largest  MIDI 
System  Exclusive  command  you  intend  to  receive.  The  default  size  of  the  input  and 
output  buffers  is  8  KB.  This  is  the  size  of  two  very  large  System  Exclusive  packets.  You 
should  choose  a  size  that  is  large  enough  to  accommodate  two  of  the  largest  System 
Exclusive  packets  you  expect  to  receive  so  that  the  MIDI  tools  can  receive  one  packet 
and  still  have  room  for  another.  In  packet  mode,  the  MIDI  Tool  Set  does  not  return  a 
packet  until  it  has  received  all  of  it,  and  MIDI  data  may  continue  to  arrive  while  the  tool 
set  is  returning  the  first  packet. 
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The  maximum  buffer  size  is  32K,  so  your  application  may  have  to  run  the  MIDI  interface  in 
raw  mode  (rather  than  packet  mode)  in  order  to  support  System  Exclusive  messages 
longer  than  16KB. 

You  might  want  to  keep  statistics  on  the  maximium  number  of  data  bytes  in  the  input 
buffer  in  order  to  allow  your  application  toadjust  the  input  buffer  size  intelligently. 
Several  MIDI  Tool  Set  calls  return  information  you  can  use  for  this  purpose;  see  "MIDI 
Tool  Calls"  in  this  chapter  for  more  detailed  information  on  data  returned  by  MIDI  tool 
calls  (especially  the  miMaxInChars  and  miMaxOutChars  functions  of  the  Midilnf  o 

call). 

Loss  of  MIDI  data 

The  Apple  6850  driver  was  designed  to  work  with  non-buffered  interface  cards.  When  you 
use  this  driver  and  the  desktop  interface  you  may  lose  MIDI  data.  To  avoid  this  data  loss, 
you  can 

■  Use  a  different,  buffered  6850-based  MIDI  card  along  with  a  driver  that  supports  the 
card 

■  Prevent  the  user  from  moving  the  cursor  or  making  menu  selections  when  your  program 
is  recording  MIDI  data 

Number  of  MIDI  interfaces 

Note  that  the  Apple  IIGS  can  support  only  a  single  MIDI  interface  at  a  time.  If  you  try  to 
support  more  than  one  MIDI  interface  at  the  same  time,  you  will  lose  MIDI  data. 
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MIDI  Housekeeping  calls 


The  following  MIDI  calls  perform  common  tool  set  functions. 


MidiBootlnit     $0120 

Initializes  the  MIDI  Tool  Set;  called  only  by  the  Tool  Locator. 

▲  Warning       An  application  must  never  make  this  call.A 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  MidiBootlnit () ; 
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MidiStartUp    $0220 

Starts  up  the  MIDI  tools  for  use  by  an  application.  Applications  should  make  this  call 
before  any  other  calls  to  the  MIDI  tools.  Normally  an  application  must  next  call 
MidiDevice  to  load  a  MIDI  device  driver,  and  then  mid i control  to  allocate  any 
necessary  input  or  output  buffers. 

Parameters 

Stack  before  call 


Previous  contents 


userlD 


dPageAddr 


Word— Application  user  ID  (for  the  Memory  Manager) 
Word— Beginning  of  MIDI  direct-page  space 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$0812  noSAppInitErr 


The  Sound  Tool  Set  has  not  been 
started  up. 


extern  pascal  void  MidiStartUp (userlD,  dPageAddr); 


Word 


userlD,    dPageAddr; 


dPageAddr  Must  specify  3  pages  of  page-aligned  direct-page  space  for  the  MIDI 

tools. 
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MidiShutDown     $0320 

Shuts  down  the  MIDI  Tool  Set.  An  application  that  uses  the  MIDI  tools  should  make  this 
call  before  it  quits.  MidiShutDown  deallocates  the  input  and  output  buffers,  stops  the 
MIDI  clock  and  deallocates  its  generator,  and  shuts  down  the  hardware  interface.  The 
call's  actions  take  place  immediately,  so  the  application  should  take  any  necessary  steps 
to  see  that  all  recent  MIDI  output  has  been  sent  before  shutting  down  the  tools  (see  the 
MidiControl  call). 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  MidiShutDown () ; 


38-28    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  1IGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


MidiVersion    $0420 

Returns  the  version  number  of  the  currently  loaded  MIDI  tools.  For  information  on  the 
format  of  the  returned  versionNum,  see  Appendix  A,  "Writing  Your  Own  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference. 


Parameters 

Stack  before  call 

Previous  contents 

Space 

Word— Space  for  result 

<— SP 

Stack  after  call 

Previous  contents 

versionNum 

Word— MIDI  tools  version  number 

<— SP 

Errors                  None 

C 

exte 

rn  pascal  Word  MidiVersion () ; 
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MidiReset     $0520 

Resets  the  MIDI  tools;  called  by  system  reset. 

This  tool  call  causes  the  MIDI  device  driver  reset  routine  to  be  invoked,  in  order  to  allow 
for  reset-specific  processing  that  may  differ  from  shutdown  processing. 


A  Warning       An  application  must  never  make  this  call.* 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  MidiReset  (); 
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MidiStatus     $0620 

Returns  a  Boolean  value  of  TRUE  if  the  MIDI  tools  are  active  and  FALSE  if  they  are  not. 


♦   Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  MidiStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  the  MIDI  Tool  Set  is  not  active,  the  returned  value  will  be 
FALSE  (NIL). 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


activeFlag 


Errors 
C 


Word— Boolean;  TRUE  if  the  tool  set  is  active 
<— SP 

None 

extern  pascal  Word  MidiStatus () ; 
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MIDI  tool  calls 

All  the  MIDI  Tool  Set  calls  are  new  calls,  added  to  the  toolbox  since  publication  of  the 
first  two  volumes  of  the  Apple  IIGS  Toolbox  Reference. 

The  routines  used  to  work  with  the  MIDI  Tool  Set  are  Midicontroi,  MidiDevice, 
MidiClock,  Midilnf  o,  MidiReadPacket,  and  MidiWritePacket.  Four  of  these 
calls  are  multifunction  calls,  which  perform  different  actions  depending  on  a  control 
parameter  passed  to  them.  The  workhorse  of  the  group  is  Midicontroi,  which  performs 
18  different  functions,  depending  on  the  control  function  parameter.  The  other 
multipurpose  calls  are  MidiDevice,  MidiClock,  and  Midilnf  o. 


38-32     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  1IGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


MidiClock    $0B20 

Controls  operation  of  the  optional  time-stamp  clock.  The  clock  ticks  once  every  76 
microseconds  with  default  settings,  and  allows  MIDI  data  to  be  input  and  output  with 
precise  timing.  The  funcNum  parameter  specifies  which  clock  function  to  perform,  and 
the  arg  parameter  provides  the  argument  to  the  selected  function. 

Parameters 

Stack  before  call 


Previous  contents 


funcNum 


arg 


Stack  after  call 


Word— Specifies  Midi  clock  function  number 
Long— Argument  passed  to  MidiClock  function 

<— SP 


Previous  contents 


Errors 
C 

funcNum 


<— SP 

See  the  MidiClock  function  descriptions  below, 
extern  pascal  void  MidiClock (funcNum,    arg); 


Word 
Long 


funcNum; 
arg; 


Specifies  the  MidiClock  function  to  be  performed.  Four  different 
functions  are  provided  for  clock  control.  They  are 


misetciock        The  value  of  arg  becomes  the  new  value  of  the  time-stamp  clock. 
The  most  significant  bit  of  the  arg  parameter  must  be  set  to  0.  There  is  a 
limit  to  the  precision  with  which  the  clock  can  be  set.  The  least 
significant  byte  of  the  time-stamp  clock  will  always  be  0  if  the  clock  is 
stopped.  If  the  clock  is  running,  the  value  of  the  least  significant  byte 
will  be  undefined  for  the  purposes  of  this  call.  The  result  is  that  an 
application  can  set  the  clock  only  to  within  20  milliseconds  of  a 
particular  value  with  the  clock  frequency  at  its  default  value. 


Errors 


None 
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miStartClock 

Allocates  a  DOC  generator,  writes  consecutive  values  from  $01  through 
$FF  into  the  first  page  of  the  DOC  RAM,  and  starts  the  clock.  By  default, 
the  clock  starts  counting  at  0.  If  the  application  stops  the  clock  and 
restarts  it,  the  clock  starts  with  the  same  value  it  had  when  it  stopped, 
unless  the  value  is  changed  with  an  misetciock  call.  Note  that  only  the 
high-order  3  bytes  are  preserved;  the  low-order  byte  always  starts  at  $01. 
You  should  call  mistartciock  before  mistartinput  if  you  are  using 
time-stamps. 

Start  the  MIDI  clock  before  starting  to  receive  or  transmit  MIDI  data. 
The  process  of  starting  the  clock  is  time-consuming  and  disables 
interrupts,  so  it  could  cause  MIDI  data  to  be  lost  if  it  is  done  while  the 
application  is  receiving  a  MIDI  transmission.  The  Sound  Tool  Set  and  the 
Note  Synthesizer  must  be  loaded  and  started  up  before  this  call  is  issued. 

Errors 

$0810  noDOCFndErr  No  DOC  or  DOC  RAM  was  found. 

$1921  nsNotAvaii    No  DOC  generator  was  available. 

$1923  nsNotmit      The  Note  Synthesizer  was  not  started. 

miStopClock 

Stops  the  MIDI  time-stamp  clock  and  releases  the  DOC  generator  and  its 
associated  RAM  for  use  by  the  Note  Synthesizer.  The  MIDI  tools 
time-stamp  MIDI  data  received  while  the  clock  is  stopped  with  the  value 
of  the  stopped  clock  in  the  high-order  3  bytes,  and  the  low-order  byte 
set  to  $00.  The  MIDI  tools  will  not  send  any  output  packets  with 
time-stamps  greater  than  the  value  of  the  stopped  clock  until  the  clock  is 
restarted  or  reset. 

Errors  None 
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misetFreq  Sets  the  frequency  for  the  MIDI  time-stamp  clock.  The  arg  parameter 
contains  the  number  of  clock  ticks  to  be  processed  per  second.  Valid 
values  lie  in  the  range  from  1  to  65,535;  a  0  value  specifies  the  default 
setting  (13,160  ticks  per  second). 

Since  the  clock  frequency  affects  the  rate  of  playback,  be  careful  to  set 
the  clock  frequency  at  playback  to  the  same  value  that  was  used  when 
the  sequence  was  recorded,  unless  you  intend  to  vary  the  tempo. 

See  the  Midi  info  call  for  information  about  how  to  read  the  current 
clock  frequency  and  value. 

Errors 

$2009        miBadFreqErr    Unable  to  set  MIDI  clock  to  the  specified 

frequency  (use  the  Midimf  o  tool  call  to 
get  the  current  value). 
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MidiControl     $0920 

Performs  18  different  control  functions  required  by  the  MIDI  Tool  Set. 

The  funcNum  parameter  selects  which  function  is  to  be  performed,  and  the  arg  parameter 
passes  any  argument  required  by  that  function. 

Parameters 

Stack  before  call 


Previous  contents 


funcNum 


arg 


Word— Specifies  MidiControl  function  number 
Long— Argument  passed  to  MidiControl  function 

<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


funcNum 


<— SP 

See  the  MidiControl  function  descriptions, 
extern  pascal  void  MidiControl (funcNum,    arg); 

Word      funcNum; 
Long      arg; 

Specifies  the  MidiControl  function  to  be  performed: 


miSetRTVec 


Sets  the  real-time  vector.  The  arg  parameter  contains  the  address  of  a 
service  routine  in  the  application.  When  the  MIDI  Tool  Set  receives  MIDI 
real-time  commands,  it  calls  this  service  routine.  A  value  of  0  in  this 
parameter  disables  the  service  routine.  See  "MIDI  Tool  Set  service 
routines"  earlier  in  this  chapter  for  more  information  on  the  real-time 
command  routine. 


Errors 


None 


38-36    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  1IGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


miSetErrVec 

Sets  the  real-time  error  vector.  The  arg  parameter  contains  the  address 

of  a  service  routine  in  the  application.  The  MIDI  Tool  Set  calls  this 

routine  in  the  event  of  a  MIDI  real-time  error.  A  value  of  0  in  the 

parameter  disables  the  service  routine.  See  "MIDI  Tool  Set  service 

routines"  earlier  in  this  chapter  for  more  information  on  the  real-time 

error  routine. 


Errors 


None 


miSetlnBuf 


Sets  the  MIDI  input  buffer.  The  arg  parameter  contains  a  pointer  to  a  6- 
byte  record.  The  fields  of  this  record  are 


$00 
$02 


—  buf Size 


bufPtr 


Word— Size  of  input  buffer  (in  bytes) 


Long— Pointer  to  buffer 


If  the  buf  Ptr  parameter  is  set  to  0,  the  MIDI  Tool  Set  will  allocate  the 
input  buffer.  If  the  buf  size  parameter  is  set  to  0,  the  MIDI  tools  will 
allocate  a  buffer  8  KB  in  size.  Note  that  these  parameters  are 
independent;  your  program  may  set  either  one  of  them  to  0.  If  the 
application  allocates  the  buffer,  it  must  be  nonpurgeable,  in  a  fixed 
location,  and  must  not  cross  bank  boundaries.  The  size  must  be  greater 
than  or  equal  to  32  bytes  and  less  than  or  equal  to  32  KB. 


Errors 

$2002  miArrayErr 

Memory  Manager  errors 


Array  was  an  invalid  size. 

Returned  unchanged. 
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3        miSetOutBuf 

Sets  the  MIDI  output  buffer.  The  arg  parameter  contains  a  pointer  to  a  6- 

byte  record.  The  fields  of  this  record  are 


$00 
$02 


bufsize  -   Word— Size  of  output  buffer  (in  bytes) 


bufptr  -   Long— Pointer  to  buffer 


If  the  buf  Ptr  parameter  is  set  to  0,  the  MIDI  Tool  Set  will  allocate  the 
output  buffer.  If  the  buf  size  parameter  is  set  to  0,  the  MIDI  Tool  Set 
will  allocate  a  buffer  8  KB  in  size.  Note  that  these  parameters  are 
independent;  your  program  may  set  either  one  of  them  to  0.  If  the 
application  allocates  the  buffer,  it  must  be  nonpurgeable,  in  a  fixed 
location,  and  must  not  cross  bank  boundaries.  The  size  must  be  greater 
than  or  equal  to  32  bytes  and  less  than  or  equal  to  32KB. 

Errors 

$2002  miArrayErr    Array  was  an  invalid  size. 

Memory  Manager  errors  Returned  unchanged 

miStartlnput 

Starts  an  interrupt-driven  process  that  reads  MIDI  data  into  the  MIDI 
Tool  Set's  input  buffer.  Any  data  being  received  when  this  call  is  made  are 
discarded  until  the  first  MIDI  status  byte  is  received.  An  application  can 
retrieve  these  data  with  a  MidiReadPacket  call.  The  arg  parameter 
contains  the  address  of  a  service  routine  to  be  called  when  the  first 
packet  is  available  in  a  previously  empty  input  buffer.  The  system  will  call 
the  service  routine  immediately  if  a  complete  MIDI  packet  is  available  in 
the  input  buffer  when  this  function  is  called.  A  value  of  0  disables  this 
service  routine. 

Errors 

$2007  miNoBufErr    No  buffer  allocated. 

$200C  miNoDevErr    No  device  driver  loaded. 
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5  miStartOutput 

Starts  an  interrupt-driven  process  that  writes  application  MIDI  data  to 
the  MIDI  Tool  Set's  output  buffer.  Your  application  uses 
MidiwritePacketcalls  to  queue  data  to  this  process.  The  arg 
parameter  contains  the  address  of  a  service  routine  called  when  the 
output  buffer  becomes  completely  empty.  A  value  of  0  disables  this 
service  routine. 

Errors 

$2007  miNoBuf  Err    No  buffer  allocated. 

$200C  miNoDevErr    No  device  driver  loaded. 

6  miStopInput 

Causes  the  MIDI  Tool  Set  to  ignore  MIDI  data  until  the  next 
miStartlnput  call. 

Errors  None 

7  miStopOutput 

Halts  MIDI  output  until  the  next  mistaftoutput  call. 

Errors  None 

8  miFlushlnput 

Discards  the  contents  of  the  current  input  buffer. 

Errors 

$2007  miNoBufErr    No  buffer  allocated. 

9  miFlushOutput 

Discards  the  contents  of  the  current  output  buffer.  The  arg  parameter 
selects  the  method: 

arg  value  Action 

$0000  00XX  Wait  for  the  current  packet  to  finish  transmission,  then 

turn  off  all  notes  that  have  not  been  turned  off  in  channel 
XX.  If  XX  -  $10,  turn  off  notes  in  all  channels. 

$0001  00XX  Wait  for  current  packet  to  finish  transmission,  then  turn 

off  all  possible  notes  (pitch  $00  through  $7F)  in  channel  XX. 
If  XX  «=  $10,  turn  off  notes  in  all  channels.  Note  that  this 
option  may  take  several  seconds  to  complete. 

$FFFFXXXX         Discard  the  contents  of  the  output  buffer  immediately 
without  turning  off  any  notes. 
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Some  synthesizers  may  require  a  short  delay  between  the  high-speed 
NoteOff  commands  generated  by  this  function.  In  such  cases,  use  the 
misetDelay  function  of  this  tool  call  to  control  that  delay.  The 
NoteOff  side-effect  can  be  useful  for  shutting  off  notes. 

Errors 

$2005  mioutof  f  Err  MIDI  output  disabled. 

$2007  miNoBuf  Err    No  buffer  allocated. 

10  miFlushPacket 

If  there  is  a  complete  packet  in  the  input  buffer,  this  call  discards  that 
packet.  If  there  is  no  complete  packet  available,  this  call  does  nothing. 
This  call  is  especially  useful  for  discarding  large  System  Exclusive  packets 
that  are  of  no  interest  to  your  application. 

Errors 

$2007  miNoBuf  Err    No  buffer  allocated. 

11  miWaitOutput 

Ceases  execution  until  the  output  buffer  becomes  empty.  This  function 

may  never  return  if  output  is  disabled. 
Errors 

$2007  miNoBufErr    No  buffer  allocated. 

12  miSetlnMode 

Set  input  mode.  The  arg  parameter  selects  the  input  mode. 

arg  value  Input  mode 

0  Raw  mode.  MIDI  data  is  converted  to  packets,  with 
length-of-packet  and  time-stamp  bytes  added  to  the  front 
of  each  packet. 

1  Packet  mode.  Packet  mode  is  the  default  mode.  MIDI 
data  is  converted  to  packets,  with  length-of-packet  and 
time-stamp  bytes  added  to  the  front  of  each  packet. 
Running  status  bytes,  which  MIDI  may  discard  to 
abbreviate  transmitted  data,  are  restored. 

The  input  buffer  is  cleared  when  this  call  is  made  because  the  input  buffer 
cannot  contain  data  in  more  than  one  format  at  a  time. 

Errors  None 
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13  miSetOutMode 

The  arg  parameter  selects  the  output  mode. 
arg  value  Input  mode 

0  Raw  mode.  This  mode  is  very  similar  to  packet  mode,  but 
no  attempt  is  made  to  keep  track  of  which  notes  are  on. 
Running  status  optimization  is  still  performed  unless 
explicidy  disabled  by  mioutputstat.  Because  no  record 
is  kept  of  which  notes  are  on,  all  notes  that  are  turned  on 
must  be  explicidy  turned  off. 

1  Packet  mode.  Packet  mode  is  the  default  mode.  Your 
application  must  format  output  data  into  valid  MIDI 
packets  (see  "MIDI  packet  format"  in  this  chapter  for 
details).  The  MIDI  tools  track  NoteOn  and  NoteOff 
commands. 

Your  program  should  wait  for  a  clear  output  buffer  before  switching 
modes.  If  the  output  buffer  contains  mixed-mode  data,  the  MIDI  tools 
may  not  track  NoteOn  and  NoteOff  commands  correcdy. 

Errors  None 

14  miClrNotePad 

Erases  the  MIDI  Tool  Set's  record  of  which  notes  are  on  and  which  are 
off.  This  call  causes  the  tool  set's  record  to  show  that  all  notes  are  off. 

Errors  None 

15  miSetDelay 

Sets  a  delay  value  for  use  with  MIDI  synthesizers  that  cannot  process 

MIDI  data  at  the  full  MIDI  transfer  rate.  The  low  word  of  arg  specifies  a 
minimum  delay  between  packet  sends  in  units  of  76  microseconds.  The 
delay  mechanism  is  most  effective  when  the  MIDI  Tool  Set  clock  is 
running,  because  it  can  use  the  clock  to  time  the  delay.  If  the  clock  is  not 
running,  the  tool  set  must  use  code  loops  to  create  the  delay,  which  is 
inherendy  less  accurate,  and  which  uses  more  processor  time.  The  default 
delay  value  is  0,  or  no  delay. 

Many  synthesizers  may  need  a  delay  value  in  order  to  correcdy  process 
the  many  high-speed  NoteOff  commands  generated  by  the 

miFlushOutput  function. 

Errors  None 
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16  miOutputStat 

Enables  or  disables  transmission  of  standard  MIDI  running  status.  When 
running  status  is  enabled,  MIDI  status  bytes  are  sent  only  when  they 
change  or  are  otherwise  absolutely  necessary.  This  optimization  speeds 
transmission  and  reduces  CPU  overhead,  but  can  cause  malfunctions  if 
the  synthesizer  and  computer  disagree  on  the  current  value  of  the  status 
byte. 

The  low  word  of  org  contains  the  enable/disable  flag 

$0000       Disable  running  status 
$0001        Enable  running  status 

Whatever  the  value  of  the  parameter,  the  next  MIDI  packet  after  this  call 
contains  a  status  byte,  so  it  can  be  useful  to  make  this  call  periodically  to 
ensure  that  the  Apple  IIGS  and  the  external  device  agree  about  the  current 
value  of  the  status  byte. 

Errors  None 

17  milgnoreSysEx 

Specifies  whether  to  ignore  MIDI  System  Exclusive  data.  System 
Exclusive  packets  begin  with  the  value  $F0.  If  the  application  configures 
the  MIDI  Tool  Set  to  ignore  System  Exclusive  packets,  the  system  will 
not  buffer  them,  and  the  application  will  not  receive  them.  The  arg 
parameter  contains  a  flag  indicating  how  to  process  System  Exclusive 
data: 

$0000       Ignore  System  Exclusive  data 

$0001        Accept  System  Exclusive  data  (default) 

Errors  None 
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MidiDevice     $0A20 

Allows  an  application  to  select,  load,  and  unload  device  drivers  for  use  with  the  tools. 
MidiDevice  loads  and  unloads  MIDI  device  drivers,  which  allow  the  MIDI  tools  to  drive 
a  particular  MIDI  interface.  The  present  version  of  the  MIDI  Tool  Set  supports  the  Apple 
MIDI  Interface  and  ACIA  6850  MIDI  Interface  cards. 

The  call  interprets  the  driverlnfo  parameter  as  the  address  of  the  driver  to  be  loaded.  The 
funcNum  parameter  specifies  whether  the  driver  is  to  be  loaded  or  unloaded. 

Parameters 

Stack  before  call 


Previous  contents 


funcNum 


drvrPtr 


Word— Specifies  MidiDevice  function  number 
Long— Pointer  to  device  driver  information 

<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


funcNum 
o 


<— SP 

See  the  MidiDevice  function  descriptions. 

extern  pascal  void  MidiDevice (funcNum,  drvrPtr); 

Word      funcNum; 
Pointer   arg; 

Specifies  the  MidiDevice  function  to  be  performed 
Not  yet  implemented 
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miLoadDrvr 


Loads  the  specified  device  driver  into  memory,  after  shutting  down  and 
unloading  any  previously  loaded  device  drivers.  It  then  initializes  the 
newly  loaded  driver.  The  drvrPtr  parameter  points  to  a  device  driver 
record,  which  specifies  a  device  driver  to  be  loaded. 


Errors 


$2008 

miDriverErr 

Specified  device  driver  invalid. 

$2080 

miDevNot Avail 

MIDI  interface  not  available. 

$2081 

miDevSlotBusy 

Specified  slot  not  selected  in  Control 
Panel. 

$2082 

miDevBusy 

MIDI  interface  already  in  use. 

$2084 

miDevNoConnect 

No  connection  to  MIDI  interface. 

$2086 

miDevVersion 

ROM  version  or  machine  type 
incompatible  with  device  driver. 

$2087 

miDevIntHndlr 

Conflicting  interrupt  handler  installed 

miUnloadDrvr 

Shuts  down  and  unloads  the  currently  loaded  device  driver.  Terminates 
MIDI  transmission  or  reception  if  they  are  currently  active.  Releases 
memory  occupied  by  the  device  driver. 


drvrPtr 


Errors 


None 


The  record  pointed  to  by  the  drvrPtr  parameter  contains  device 
driver  information: 


$00 
$02 
$04 


slotNumber 


slotFXag  —    Word 


Word 


driverpath  :  Pascal  string 


slotNumber  Specifies  the  system  slot  containing  the  MIDI  interface  to  be 
supported  by  the  driver  being  loaded.  Valid  values  range  from 
$0000  through  $0007. 
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siotFiag  Indicates  whether  type  of  slot  specified  in  siotNumber: 

$0000         Internal  slot 
$0001         External  slot 

driverPath        Pascal  string  containing  the  GS/OS™  pathname  to  the  file 

containing  the  device  driver  to  be  loaded.  Pascal  strings  consist 
of  data  preceded  by  a  length  byte.  The  pathname  cannot  exceed 
64  characters  in  length. 
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Midilnfo    $0C20 


Returns  certain  information  about  the  state  of  the  MIDI  tools.  The  funcNum  parameter 
can  specify  nine  different  functions,  whose  results  are  returned  in  infoResult. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


funcNum 


Stack  after  call 


Long— Space  for  result 

Word— Specifies  Midiinf  o  function  number 

<— SP 


Previous  contents 


infoResult 


Long— Result  of  Midiinf  o  function 
<— SP 

Errors  See  the  Mi di info  function  descriptions . 

C  extern  pascal   Long  Midilnfo (funcNum)  ; 

Word  funcNum; 

funcNum         Specifies  the  Midiinf  o  function  to  be  performed 

0  miNextPktLen 

Returns  the  number  of  bytes  in  the  next  MIDI  packet.  On  return, 
infoResult  contains  the  length  of  the  next  complete  MIDI  packet  in  the 
input  buffer,  including  the  four-byte  time-stamp  at  the  beginning  of  the 
packet.  Note  that  if  there  is  no  complete  packet  in  the  input  buffer,  this 
function  returns  a  value  of  0. 


Errors 

$2007 


miNoBufErr    No  buffer  allocated. 
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1  milnputChars 

Returns  the  number  of  bytes  of  MIDI  data  waiting  in  the  input  buffer.  On 
return,  infoResult  contains  the  number  of  bytes  of  MIDI  data  currently 
stored  in  the  input  buffer,  including  any  time-stamp  and  length  data  (6 
bytes  per  packet),  error  codes,  and  up  to  12  bytes  of  extra  space  at  the 
end  of  the  buffer  due  to  call  latency.  It  is  therefore  only  a  rough  estimate 
of  the  number  of  bytes  in  the  buffer.  Your  application  an  use  this  call  to 
monitor  whether  the  input  buffer  is  large  enough. 

Errors 

$2007  miNoBuf  Err    No  buffer  allocated. 

2  miOutputChars 

Returns  the  number  of  bytes  of  MIDI  data  waiting  in  the  output  buffer. 
On  return,  infoResult  contains  the  number  of  bytes  waiting  to  be 
transmitted  from  the  MIDI  output  buffer,  including  time-stamp  and 
length  data  (6  bytes  per  packet),  error  codes,  and  up  to  12  bytes  of  extra 
space  at  the  end  of  the  buffer  due  to  call  latency.  It  is  therefore  only  a 
rough  estimate  of  the  number  of  bytes  in  the  buffer.Your  application  can 
use  this  call  to  monitor  whether  the  output  buffer  is  large  enough. 

Errors 

$2007  miNoBuf  Err    No  buffer  allocated. 

3  miMaxInChars 

Returns  the  largest  number  of  bytes  that  were  stored  in  the  input  buffer 

since  the  last  miMaxInChars  call  or  since  the  buffer  was  last  flushed. 
This  call  is  especially  useful  for  deriving  statistics  on  buffer  utilization. 

Errors  None 

4  miMaxOutChars 

Returns  the  largest  number  of  bytes  that  were  stored  in  the  output  buffer 

since  the  last  miMaxOutChars  call  or  since  the  output  buffer  was  last 
flushed.  This  call  is  especially  useful  for  deriving  statistics  on  buffer 
utilization. 

Errors  None 

5  Not  yet  implemented 

6  Not  yet  implemented 
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7  miClockValue 

Returns  the  current  value  of  the  MIDI  Tool  Set  time-stamp  clock.  If  the 

clock  is  stopped  then  the  low-order  byte  of  the  result  is  0. 
Errors  None 

8  miClockFreq 

Returns  the  current  MIDI  Tool  Set  clock  frequency  in  ticks  per  second. 

The  default  value  is  13,160  ticks  per  second. 
Errors  None 
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MidiReadPacket     $0D20 

Moves  MIDI  data  from  the  MIDI  Tool  Set's  input  buffer  to  a  specified  location  and 
returns  the  length  of  the  packet  in  bytes.  If  no  packet  is  available,  the  call  returns  a  0.  For 
more  information  on  MIDI  packets,  see  "MIDI  packet  format"  earlier  in  this  chapter. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


bufPtr 


bufSize 


Word— Space  for  result 
Long— Pointer  to  buffer  for  received  data 
Word— Length,  in  bytes,  of  the  receive  buffer 
<— SP 


Stack  after  call 


Previous  contents 


result 


Errors 


Word— Number  of  bytes  actually  returned 
<— SP 


$2001 

miPacketErr 

Incorrect  packet  length  received 

$2002 

miArrayErr 

Array  was  an  invalid  size.  The 
array  was  too  small  to  store  the 
next  packet.  Use  a  larger  array  or 
discard  the  packet  with  the 

MidiControl  Call. 

$2003 

miFullBufErr 

MIDI  data  discarded  because  of 
buffer  overflow. 

$2007 

miNoBufErr 

No  buffer  allocated. 

$2083 

miDevOverrun 

MIDI  interface  overrun  by  input 
data;  interface  not  serviced 
quickly  enough. 

$2084 

miDevNoConnect 

No  connection  to  MIDI 
interface. 

$2085 

miReadErr 

Error  reading  MIDI  data. 
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extern  pascal  Word  MidiReadPacket (buf Ptr,  buf Size) ; 

Pointer   bufPtr; 
Word      bufSize; 
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MidiWritePacket     $0E20 

Queues  the  specified  MIDI  packet  into  the  MIDI  Tool  Set's  output  buffer.  If  the  packet 
is  successfully  written  to  the  output  buffer,  this  call  returns  the  number  of  bytes  written.  If 
the  buffer  is  too  full  to  accommodate  the  packet,  MidiWritePacket  returns  0.  For 
more  information  on  MIDI  packets,  see  "MIDI  packet  format"  in  this  chapter. 

MidiWritePacket  returns  within  Hoof  a  second,  but  the  output  process  waits  until  the 
MIDI  clock  value  is  equal  to  or  greater  than  the  output  packet's  time-stamp  before 
sending  it.  Your  program  should  issue  this  call  before  before  starting  the  MIDI  output 
process  (with  the  mistartoutput  function  of  the  MidiControi  tool  call). 

In  packet  mode,  MidiWritePacket  assumes  that  only  complete  MIDI  commands  are 
passed  to  it,  and  that  the  first  byte  of  each  packet  is  a  MIDI  status  byte.  The  MIDI  Tool 
Set  uses  these  assumptions  to  track  NoteOn  and  NoteOff  commands.  In  raw  mode  the 
MIDI  Tool  Set  makes  no  attempt  to  track  NoteOn  and  NoteOff  commands,  so  the 
intelligent  NoteOff  function  provided  in  MidiControi  will  not  work,  and  packets  may 
contain  complete,  partial,  or  multiple  MIDI  commands.  In  either  mode  the  MIDI  Tool  Set 
omits  the  MIDI  status  byte  unless  its  value  has  changed  since  the  last  one  was  transmitted. 
You  can,  however,  disable  running  status  transmission  entirely  by  using  the  MidiControi 
call. 

If  the  MIDI  clock  is  stopped,  then  all  packets  with  a  time-stamp  less- than  or  equal  to  the 
value  of  the  clock  are  immediately  transmitted,  and  all  packets  with  a  value  greater  than 
the  clock  remain  in  the  buffer  unless  the  clock  is  restarted  and  its  value  becomes  greater 
than  the  time-stamps. 

Two  special  time-stamp  values  override  normal  output  buffer  processing,  irrespective  of 
MIDI  clock  state.  Any  packet  with  a  zero  time-stamp  is  written  immediately  upon 
reaching  the  head  of  the  output  buffer.  Any  packet  with  a  negative  time-stamp  value  is 
considered  to  be  a  real-time  command  and  the  packet  is  inserted  at  the  head  of  the 
output  queue  for  immediate  transmission.  Note  that  MIDI  real-time  messages  may  be 
transmitted  in  the  middle  of  non-real-time  MIDI  messages. 

The  MIDI  Tool  Set  routines  do  not  sort  the  packets  in  the  output  buffer,  therefore,  a 
packet  at  the  head  of  the  output  queue  can  delay  transmission  of  any  packets  behind  it 
that  have  earlier  time-stamp  values. 
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Parameters 

Stack  before  call 

Previous  contents 

Space 

Word— Space  for  result 

bufPtr 

Long— Pointer  to  buffer  containing  output  data 

<— SP 

Stack  after  call 

Previous  contents 

bytesWritten 

Word— Number  of  bytes  actually  written 

<— SP 

Errors                  None 

C 

exte 

rn  pascal  Word  MidiWritePacket (bufPtr) ; 

Pointer        bufPtr; 
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MIDI  Tool  Set  error  codes 


This  section  lists  the  error  codes  that  may  be  returned  by  MIDI  Tool  Set  calls. 


Value 


Name 


Definition 


$2000 

miStartUpErr 

$2001 

miPacketErr 

$2002 

miArrayErr 

$2003 

miFullBufErr 

$2004 

miToolsErr 

$2005 

miOutOffErr 

$2007 

miNoBufErr 

$2008 

miDriverErr 

$2009 

miBadFreqErr 

$200A 

miClockErr 

$200B 

miConflictErr 

$200C 

miNoDevErr 

$2080 

miDevNot Avail 

$2081 

miDevSlotBusy 

$2082 

miDevBusy 

$2083 

miDevOve  r run 

$2084 

miDevNoConnect 

$2085 

miDevReadErr 

$2086 

miDevVersion 

$2087 

miDevI ntHndl r 

MIDI  Tool  Set  not  started  up. 

Incorrect  packet  length  received. 

Array  was  an  invalid  size. 

MIDI  data  discarded  because  of  buffer  overflow. 

Required  tools  inactive  or  incorrect  version. 

MIDI  output  disabled. 

No  buffer  allocated. 

Specified  device  driver  invalid. 

Unable  to  set  MIDI  clock  to  the  specified 

frequency  (use  the  Midi  info  tool  call  to  get  the 

current  value). 

MIDI  clock  wrapped  to  0. 

Two  processes  competing  for  MIDI  input. 

No  device  driver  loaded. 

MIDI  interface  not  available. 

Specified  slot  not  selected  in  Control  Panel. 

MIDI  interface  already  in  use. 

MIDI  interface  overrun  by  input  data;  interface 

not  serviced  quickly  enough. 

No  connection  to  MIDI  interface. 

Error  reading  MIDI  data. 

ROM  version  or  machine  type  incompatible  with 

device  driver. 

Conflicting  interrupt  handler  installed. 
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Chapter  39   Miscellaneous  Tool  Set  Update 


This  chapter  documents  new  features  of  the  Miscellaneous  Tool  Set.  The 
complete  reference  to  the  Miscellaneous  Tools  is  in  Volume  1,  Chapter  14 
of  the  Apple  IIGS  Toolbox  Reference. 
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Error  corrections 

■   On  page  14-58  of  the  Toolbox  Reference,  Figure  14-3  shows  the  low-order  bit  of  the  User 
ID  is  reserved.  This  is  not  correct.  The  figure  should  show  that  the  mainiD  field 
comprises  bits  0-7,  and  that  the  mainiD  value  of  $00  is  reserved. 

The  sample  code  on  page  14-28  contains  an  error.  In  the  code  to  clear  the  1  second  IRQ 
source,  the  second  instruction  reads 

TSB         $C032 

This  instruction  should  read 

TRB         $C032 

The  descriptions  of  the  PackBytes  and  unPackBytes  tool  calls  are  unclear  with 
respect  to  the  startHandle  parameter  to  each  call.  The  stack  diagrams  correctly 
describe  the  parameter  as  a  pointer  to  a  pointer.  However,  the  C  sample  code  for  each 
call  defines  startHandle  as  a  handle.  In  both  cases,  startHandle  is  not  a  Memory 
Manager  handle,  but  is  a  pointer  to  a  pointer.  Creating  startHandle  as  a  handle  will 
cause  unpredictable  system  behavior. 


New  features  in  the  Miscellaneous  Tool  Set 

■  ciearHeartBeat  and  DeieteHeartBeat  will  turn  off  the  interrupts  that  occur 
every  60th  of  a  second  if  the  following  conditions  are  satisfied: 

d  There  are  no  remaining  heartbeat  tasks. 

d   The  interrupt  handler  installed  in  IRQ.VBL  is  the  standard  system  interrupt  handler, 
that  is,  no  other  interrupt  handlers  have  been  installed. 

□   The  standard  mouse  is  not  running  in  VBL  interrupt  mode. 

■  setvector  and  Getvector  support  several  new  vectors.  The  new  vectors  are: 

$80  Vector  to  memory  mover 

$81  Vector  to  set  system  speed 

$82  Vector  to  slot  arbiter 

$86  Hardware  independent  interrupt  vector 

$87  MIDI  interrupt  vector  (IRQ-MIDI) 

♦   Note:  setvector  no  longer  validates  the  input  vector  number.  Therefore,  you  must 
be  extremely  careful  when  using  this  all  in  order  to  avoid  corrupting  memory. 
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Queue  handling 

The  Miscellaneous  Tool  Set  now  provides  a  generalized  queue  handler  that  can  be  used  by 
other  tools  and  applications.  A  queue  is  defined  here  as  an  ordered  collection  of  variable- 
length  data  elements.  Each  data  element  must  be  preceded  by  a  standard  queue  header. 
Your  application  must  format  the  queue  elements  and  format  the  correct  header.  The 
queue  handler  provides  calls  to  add  or  remove  elements  from  a  queue  (AddToQueue  and 
DeleteFromQueue). 

A  queue  is  identified  by  its  header  pointer,  a  pointer  to  the  first  element  in  the  queue. 
Your  application  establishes  and  maintains  the  header  pointer.  Do  not  add  this  first 
element  to  the  queue  with  AddToQueue. 

Figure  39-1  shows  the  format  of  the  queue  header. 


Figure  39-1      Queue  header  layout 


$00 

$04 
$06 


Reserved 


Reserved 


signature  — 


Long— Link  to  next  item  in  queue— set  by  queue  handler 

Word— Reserved  for  system  use 

Word— Validates  header—must  be  set  to  $A55A 


Application  data  immediately  follow  the  header. 

See  "New  Miscellaneous  Tool  Set  calls"  later  in  this  chapter  for  details  on  AddToQueue 
and  DeleteFromQueue. 
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Interrupt  state  information 

The  Miscellaneous  Tool  Set  now  provides  a  set  of  calls  that  allow  you  to  obtain  interrupt- 
time  system  state  information.  These  calls  should  be  particularly  useful  to  developers  of 
debuggers  or  interrupt  handlers.  With  these  new  calls,  your  program  can  get  or  set  system 
interrupt  state  information. 

All  these  new  calls  use  a  standard  interrupt  state  record.  Note  that  the  tool  calls  have  been 
designed  to  support  an  extensible  state  record.  In  the  future,  the  record  may  grow  in  size, 
but  existing  program  code  should  still  work. 

Figure  39-2  shows  the  format  of  the  interrupt  state  record.  For  more  information  about 
any  of  these  registers,  see  the  Apple  IIGS  Firmware  Reference. 


Figure  39-2      Interrupt  state  record  layout 


$00 

-       irq_A      - 

$02 

-        irq_X       - 

$04 

-       irq_Y       - 

$06 

-       irq_S       - 

$08 

-       irq_D       - 

$0A 

irq_P 

$0B 

irq_DB 

$0C 

irq_e 

$0D 

irq_K 

$0E 

-      irq_PC      - 

$10 

irq_state 

$11 

—    irq_shadow    — 

$13 

irqjnslot 

Word— A  register  contents 
Word— X  index  register  contents 
Word— Y  index  register  contents 
Word— S  (stack)  register  contents 

Word— D  (direct)  register  contents 

Byte— P  (program  status)  register  contents 
Byte— DB  (data  bank)  register  contents 
Byte— Bit  0  is  the  emulation  mode  bit 
Byte— K  (program  bank)  register  contents 

Word— PC  (program  counter)  register  contents 

Byte— STATEREG  byte  value 

Word-SHADOW  byte  (low  byte)  and  CYAREG  (high  byte)  values 

Byte-SLTlOMSELbyte 
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New  Miscellaneous  Tool  Set  calls 

The  following  sections  introduce  several  new  Miscellaneous  Tool  Set  calls. 


AddToQueue    $2E03 

Adds  the  specified  entry  to  a  queue. 

Parameters 

Stack  before  call 


Previous  contents 


-    newEntryPtr    - 


headerPtr 


Long— Pointer  to  element  to  add  to  queue 
Long— Pointer  to  first  queue  element 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 
$0381  invalidTag 

$0382  alreadylnQueue 


Signature  value  invalid  in  element 

header 

Specified  element  already  in 

queue 


extern  pascal  void  AddToQueue (newEntryPtr, 
headerPtr) ; 

Pointer   newEntryPtr,  headerPtr; 
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DeleteFromQueue     $2F03 

Deletes  a  specified  element  from  a  queue. 

Parameters 

Stack  before  call 


Previous  contents 


entryPtr 


headerPtr 


Stack  after  call 


Previous  contents 


Errors 


Long— Pointer  to  element  to  delete  from  queue 

Long— Pointer  to  first  queue  element 
<— SP 


<— SP 
$0380         notlnList 

$0381  invalidTag 


Specified  element  not  found  in 

queue 

Signature  value  invalid  in  element 

header 


extern  pascal  void  DeleteFromQueue (entryPtr, 
headerPtr) ; 

Pointer   entryPtr,  headerPtr; 
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GetCodeResConverter     $3403 

Returns  the  address  of  a  routine  that  loads  code  resources.  This  is  a  Miscellaneous  tool  call 
because  the  loader  is  not  in  directly  accessible  memory  (it  lives  in  the  bank  1  language 
card,  which  may  or  may  not  be  addressable  at  any  given  time). 

Your  program  would  use  this  call  in  conjunction  with  the  ResourceConverter  Resource 
Manager  tool  call  (see  Chapter  45,  "Resource  Manager,").  For  example,  the  Control 
Manager  issues  the  following  call  during  its  startup  processing: 

ResourceConverter (GetCodeResConverter ( )  , 
rCtlDefProc, 
LogConverterln+SysConverterList ) ; 

After  issuing  this  call,  all  future  calls  to  the  Resource  Manager  to  load  resources  of  type 
rCtiDef  Proc  will  use  the  Miscellaneous  tools  routine  to  bring  the  resource  into  memory. 
Note  that  this  routine  does  not  preserve  preserve  the  memory  attributes  of  the  converted 
resource  (for  more  information  on  resource  converters,  see 
Chapter  45,  "Resource  Manager,"  later  in  this  book). 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Long— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


pointer 


Long— Pointer  to  code  resource  converter  routine 
<— SP 


Errors 
C 


None 


extern  pascal  Pointer  GetCodeResConverter () ; 
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GetlnterruptState     $3103 

Copies  the  specified  number  of  bytes  into  a  specified  input  interrupt  state  record  from 
the  system  interrupt  variables.  The  copy  always  starts  from  the  beginning  of  the  interrupt 
state  record.  Use  the  setmterruptstate  call  to  set  the  contents  of  the  system 
interrupt  state  record. 

Parameters 

Stack  before  call 


Previous  contents 


-  intStateRcdPtr  - 


bytesDesired 


Stack  after  call 


Long— Pointer  to  interrupt  state  record 

Word— Number  of  bytes  to  copy  from  system  to  record 

<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  GetlnterruptState (intStateRcdPtr, 
bytesDesired) ; 

Pointer   intStateRcdPtr; 
Word      bytesDesired; 
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GetlntStateRecSize         $3203 

Returns  the  size  (in  bytes)  of  the  interrupt  state  record.  This  call  allows  application 
programs  to  work  with  extended  interrupt  state  records. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


sizeOfRecord 


Errors 
C 


Word— Length  of  interrupt  state  record,  in  bytes 
<— SP 

None 

extern  pascal  Word  GetlntStateRecSize () ; 


GetROMResource    $3503 

This  call  is  only  for  use  by  system  firmware 
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ReadMouse2    $3303 

Returns  the  mouse  position,  status,  and  mode.  This  call  does  not  support  journaling.  Refer 
to  Chapter  14,  "Miscellaneous  Tool  Set,"  in  Volume  1  of  the  Toolbox  Reference  for 
information  about  the  ReadMouse  tool  call. 


A  Warning       Applications  should  never  make  this  call., 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Space 


Space 


Stack  after  call 

Previous  contents 


xPosition 


yPosition 


statusMode 


Errors 
C 


$0309 


Word— Space  for  result 
Word— Space  for  result 
Word— Space  for  result 
<— SP 


Word— X  position  of  mouse 
Word— Y  position  of  mouse 
Word— Status  and  mode  bytes 
<— SP 


unCnctdDevErr 


Pointing  device  is  not  connected 


extern  pascal  MouseRec  ReadMouse2 ( ) ; 


ReleaseROMResource    $3603 

This  call  is  only  for  use  by  system  firmware 
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SetlnterruptState    $3003 

Copies  the  specified  number  of  bytes  from  the  input  interrupt  state  record  into  the 
system  interrupt  variables.  The  copy  always  starts  from  the  beginning  of  the  interrupt 
state  record.  Use  the  Getmterruptstate  call  to  read  the  system  interrupt  state 
record. 

Parameters 

Stack  before  call 


Previous  contents 


-  intStateRcdPtr  - 


bytesDesired 


Stack  after  call 


Long— Pointer  to  interrupt  state  record 

Word— Number  of  bytes  to  copy  from  record  to  system 

<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SetlnterruptState (intStateRcdPtr, 
bytesDesired) ; 


Pointer   intStateRcdPtr; 
Word      bytesDesired; 
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Chapter  40   Note  Sequencer 


This  chapter  documents  the  Note  Sequencer.  This  is  new  documentation, 
not  previously  presented  in  the  Apple  IIGS  Toolbox  Reference. 
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About  the  Note  Sequencer 

The  Note  Sequencer  is  a  collection  of  routines  that  implement  a  sequencer  in  the 
Apple  IIGS.  The  sequencer  is  an  interpreter  for  a  simple  music  programming  language 
designed  to  play  music  in  the  background.  It  can  be  used  to  play  music  from  a  static  file 
as  long  as  any  other  active  system  tasks  do  not  disable  interrupts. 

This  sequencer  plays  melodies  by  using  data  stored  in  a  specific  format.  It  does  not 
provide  the  means  to  create  these  data  structures,  and  so  an  application  must  provide  its 
own  tools  for  building  new  sequences. 

The  Note  Sequencer  works  with  the  Note  Synthesizer,  and  it  can  work  with  the  MIDI  tools 
if  you  choose. 

♦   Note:  The  Note  Synthesizer,  the  Note  Sequencer,  and  the  MIDI  Tool  Set  refer  to  the 
software  tools  provided  with  the  Apple  IIGS,  not  to  any  separate  instrument  or 
device.  The  MIDI  tools  are  software  tools  for  use  in  controlling  external  instruments, 
which  may  be  connected  through  a  MIDI  interface  device. 
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Using  the  Note  Sequencer 

To  use  the  Note  Sequencer,  you  must  have  loaded  the  following  tool  sets 

■  Tool  Locator 

■  Memory  Manager 

■  Sound  Tool  Set 

■  Note  Synthesizer 

■  MIDI  Tool  Set  (if  MIDI  is  to  be  used) 

All  the  required  tool  sets  must  be  started  up  except  the  Sound  Tool  Set  and  the  Note 
Synthesizer.  The  Note  Sequencer  makes  the  appropriate  calls  to  start  up  these  two  tool 
sets.  Refer  to  Chapter  51,  "Tool  Locator  Update,"  for  information  on  the  specific  version 
requirements  of  the  Note  Sequencer. 

The  Note  Sequencer  is  interrupt-driven  and  can  run  in  the  background  while  other 
application  tasks  take  place  in  the  foreground.  Therefore,  interrupts  must  not  be  disabled 
while  a  sequence  is  being  played.  Any  activity  that  disables  interrupts  interferes  with 
execution  of  a  sequence.  Disk  access,  for  example,  disables  interrupts,  so  an  application 
cannot  simultaneously  gain  access  to  a  disk  and  play  a  sequence  with  the  Note  Sequencer. 
Note  as  well  that  any  custom  error  and  completion  routines  your  application  provides  to 
the  Note  Sequencer  (see  "Error  handlers  and  completion  routines"  in  this  chapter)  also  run 
with  interrupts  disabled  and  with  a  very  low  stack. 

An  application  can  normally  rely  on  the  Note  Sequencer's  built-in  functions  to  synchronize 
a  sequence  correcdy.  For  those  applications  that  must  directly  control  the  timing  of 
sequence  execution,  the  stepSeq  call  has  been  provided.  This  call  enables  an  application 
to  explicidy  control  the  execution  of  a  sequence  one  step  at  a  time. 


Sequence  timing 

Normally  you  might  think  of  a  musical  sequence  as  several  independent  tracks  playing  at 
the  same  time.  For  example,  a  musical  passage  might  consist  of  a  violin  sound  playing  a 
melody  accompanied  by  a  viola  and  a  flute.  Musically,  the  three  instruments  will  often  play 
at  once,  sounding  different  notes.  The  Note  Sequencer,  however,  always  plays  notes  in 
sequence,  one  after  another,  however  many  instruments  it  is  using  to  play  them. 
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A  chord,  which  is  musically  a  group  of  different  notes  played  at  the  same  time,  is  executed 
by  the  Note  Sequencer  as  a  series  of  discrete  notes  played  very  quickly  one  after  the 
other.  For  example,  the  Note  Sequencer  would  play  a  chord  consisting  of  F  above  middle 
C,  A  above  middle  C,  and  C  one  octave  above  middle  C  as  a  series  of  note  commands: 

Note  Duration 


F4 

4  counts 

PA 

4  counts 

C5 

4  counts 

If  the  Note  Sequencer  waited  for  each  note  to  finish  before  beginning  the  next  one,  the 
resulting  passage  would  be  three  distinct  notes  of  equal  length,  which  is  not  what  was 
intended.  The  Note  Sequencer  therefore  provides  a  way  to  play  the  three  notes  with  very 
little  delay  between  them;  so  little,  in  fact,  that  they  sound  as  though  they  were  being 
played  all  at  once. 

If  the  chord  bit  is  set  to  1  in  a  note  command,  it  indicates  that  the  next  note  should  be 
played  to  sound  a  chord  with  the  current  one.  If,  on  the  other  hand,  the  delay  bit  is  set 
to  1,  it  indicates  that  the  current  note  must  be  completed  before  the  next  one  is  played. 


Using  MIDI  with  the  Note  Sequencer 

The  appropriate  calls  must  be  made  to  the  MIDI  Tool  Set  to  use  MIDI  with  the  Note 
Sequencer.  Specifically,  the  MIDI  tools  must  be  started  up,  a  device  driver  must  be 
selected,  and  a  MIDI  output  buffer  must  be  allocated  (see  Chapter  38,  "MIDI  Tool  Set,"  in 
this  book  for  details).  In  addition,  you  must  start  the  MIDI  output  process  by  issuing  the 
miStartOutput  function  of  the  MidiControl  tool  call. 

You  must  specify  whether  MIDI  is  to  be  used  when  you  start  up  the  Note  Sequencer.  If  the 
high  bit  of  the  mode  parameter  is  set  when  the  seqstartup  call  is  made,  then  MIDI  is 
enabled.  If  a  particular  track  is  to  use  MIDI,  it  must  be  enabled  for  that  track,  using  the 
setTrkinf  o  call.  Finally,  the  Note  Sequencer  checks  tool  call-specific  and  seqltem- 
specific  flags  for  MIDI  information,  so  that  individual  tool  calls  or  commands  can  enable 
or  disable  MIDI. 

If  all  the  appropriate  flags— the  mode  flag,  the  track  flag,  and  the  command  or  tool  call 
flag— are  enabled,  then  MIDI  commands  are  sent  to  external  MIDI  devices.  This 
arrangement  is  designed  to  provide  flexibility  in  execution.  You  could,  for  example,  play 
only  the  drum  parts  of  a  sequence  on  external  MIDI  instruments,  by  enabling  MIDI  output 
only  on  the  appropriate  tracks,  or  you  could  play  all  parts  on  external  MIDI  instruments. 
Switching  between  the  two  modes  of  play  would  not  require  any  modification  of  the 
sequence  itself. 
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The  Note  Sequencer  as  a  command  interpreter 

The  Note  Sequencer  is  actually  a  command  interpreter.  The  commands  it  interprets  are  32- 
bit  data  structures  called  seqltems,  or  sequence  items.  These  32-bit  items  contain 
information  that  the  Note  Sequencer  needs  to  classify  them  as  note  commands,  control 
commands,  MIDI  commands,  or  register  commands,  and  to  execute  them  properly. 

The  format  of  a  seqltem  is  detailed  in  Figure  40-1. 


Figure  40-1      Format  of  a  seqltem 


Bits 


31 

16 

15 

14 

8 

7 

6 

0 

tail 

n 

vail 

chord 

cmd 

cmd 


chord 


vail 


note 


tail 


For  all  commands  except  note  commands,  this  is  the  command 
identifier,  a  7-bit  number  that  uniquely  identifies  the  command.  For 
example,  the  vibrato  depth  command  has  a  cmd  value  of  4. 

The  chord  bit  is  a  Boolean  value.  If  set,  it  specifies  that  the  Note 
Sequencer  should  immediately  execute  the  next  seqltem  with  no 
delay. 

The  meaning  of  the  vail  field  depends  on  the  command  being 
issued. 

The  note  bit  identifies  note  commands.  If  bit  n  is  set,  the  seqltem  is 
a  note  command. 

The  format  of  the  tail  field  depends  upon  the  command  type.  It 
contains  two  or  more  fields  with  command-specific  information  in 
them. 


There  are  four  types  of  seqltems:  note  commands,  control  commands,  MIDI  commands, 
and  register  commands.  Each  type  is  organized  in  the  same  way,  but  the  values  in  each 
part  of  the  data  structure  have  different  meanings  in  the  different  commands. 
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Error  handlers  and  completion  routines 

The  Note  Sequencer  provides  facilities  allowing  application  programs  to  gain  control  at 
the  end  of  a  sequence,  and  when  any  errors  are  encountered  during  sequence  processing. 
The  Note  Sequencer  invokes  completion  routines  when  it  has  finished  a  sequence.  The 
completion  routine  can  then  perform  any  necessary  application-specific  processing. 
Similarly,  when  an  error  occurs  during  sequence  processing,  the  Note  Sequencer  calls  a 
specified  error  handler,  which  can  process  the  error  in  a  manner  appropriate  to  the  current 
application. 

When  you  start  a  sequence  with  the  startseq  tool  call,  you  may  specify  a  completion 
routine,  an  error  handler,  or  both  for  the  sequence.  The  compRoutine  parameter  points  to 
the  completion  routine;  the  errHndlrRoutine  parameter  specifies  the  error  Handler.  Zero 
values  for  either  parameter  indicate  to  the  Note  Sequencer  that  there  is  no  custom  routine 
of  the  appropriate  type  available. 

On  entry  to  either  type  of  routine,  the  Note  Sequencer  sets  up  the  following  conditions: 

■  Interrupts  disabled 

■  Direct  page  set  for  Note  Sequencer  data  area 

■  Data  bank  set  to  its  value  at  the  time  of  initial  seqstartup  tool  call  for  the 
application;  Note  Sequencer  restores  this  value  when  the  routines  return 

■  All  registers  saved 

■  Very  little  stack  available 

When  a  sequence  started  by  startseq  reaches  its  end,  control  will  pass  to  the  routine 
specified  by  compRoutine. 

Whenever  an  error  is  encountered  during  sequence  processing,  the  Note  Sequencer  will  try 
to  call  the  error  handler  for  the  sequence.  A  useful  function  of  an  error  handler  might  be  to 
place  an  error  flag  for  the  completion  routine  and  make  a  GetLoc  call  to  determine  the 
location  of  the  error. 

The  Note  Sequencer  passes  error  codes  to  the  error  handler  in  the  A  register.  In  step  mode, 
the  Note  Sequencer  will  both  report  the  error  condition  to  the  error  handler  and  post  it  in 
the  A  register  at  the  completion  of  the  call  to  stepseq.  In  interrupt  mode,  the  Note 
Sequencer  will  only  report  the  error  to  the  application  error  handler. 

♦   Note:  The  Note  Synthesizer's  timer  oscillator  is  not  forced  on  when  an  error  occurs  in 
the  startseq  call;  neither  the  Note  Synthesizer  nor  the  Sound  Tool  Set  will  have  been 
started. 
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Note  commands 

Note  commands  switch  notes  on  and  off.  You  can  use  note  commands  in  two  ways.  You 
can  issue  a  pair  of  NoteOn  and  NoteOff  commands,  turning  a  specified  note  on  at  a 
certain  point  and  then  explicitly  turning  it  off,  or  you  can  issue  a  NoteOn  command  with  a 
duration  specified.  In  this  case  the  Note  Sequencer  plays  the  note  for  a  number  of  ticks 
equal  to  the  value  of  the  duration  parameter,  then  turns  the  note  off  without  the  need  for 
an  explicit  NoteOff  command.  Each  tick  occurs  at  an  interval  set  by  the  Note 
Synthesizer's  update  rate  (see  Chapter  41,  "Note  Synthesizer,"  in  this  book  for  details). 


Figure  40-2      Note  command  format 


Bits 

31  30 


27  26 


16  15  14 


d 

trk 

duration 

n 

pitch 

chord 

volume 

volume 


chord 


pitch 


note 


duration 


Specifies  note  volume.  Corresponds  to  MIDI  velocity.  A  value  of  0 
indicates  a  NoteOff  command. 

Indicates  that  the  seqltem  is  to  be  played  simultaneously  with  the 
next  seqltem.  Do  not  set  both  the  chord  bit  and  the  delay  bit  in  the 
same  item. 

Selects  the  pitch  to  be  played.  Values  may  range  from  0  to  127.  A  value 
of  60  selects  middle  C  (261.6  Hz).  Adjacent  values  are  one  semitone 
apart.  A  value  of  0  specifies  a  filler  note  (see  "Filler  notes"  in  this 
chapter  for  details). 

Always  set  to  1  for  note  commands.  If  this  bit  is  not  set  to  1  in  a 
seqltem,  then  the  seqltem  is  not  a  note  command. 

Specifies  the  length  of  time  the  Note  Sequencer  is  to  play  the  note. 
Values  may  range  from  0  to  2047,  and  specify  the  number  of  ticks  the 
note  is  to  be  played. 

A  duration  of  0  identifies  the  seqltem  as  a  NoteOn  command.  A 
NoteOn  seqltem  is  played  continuously  until  the  Note  Sequencer 
finds  a  matching  NoteOff. 
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trk 


delay 


Track  number.  Assigns  notes  to  synthesizer  voices  and  MIDI  channels 
by  specifying  their  track  numbers.  Values  from  $0  to  $F  are  legal.  Refer 
to  the  description  of  the  Set  Trk  info  call  for  more  information. 

If  this  bit  is  set  to  1,  the  Note  Sequencer  must  finish  playing  this 
seqltem  before  beginning  to  play  the  next  one.  The  Note  Sequencer 
cannot  advance  to  the  next  seqltem  until  the  duration  is  past.  Do 
not  set  this  bit  to  1  if  the  chord  bit  is  set  to  1. 


Filler  notes 

Filler  notes  are  used  to  fill  spaces  in  musical  sequences.  Intuitively,  you  might  suppose 
that  an  application  should  use  delays  to  create  rests,  but  during  a  delay  the  Note 
Sequencer  delays  all  its  operations.  Not  only  does  it  not  play  any  notes  until  the  delay 
period  has  elapsed,  it  also  does  not  perform  other  services,  such  as  turning  notes  off.  You 
could  cause  strange  behavior  in  a  sequence  if  you  used  delays  to  create  rests. 

An  alternative  approach  is  to  use  filler  notes.  A  filler  note  is  simply  a  note  command  with  a 
pitch  value  of  0.  Such  a  note  will  be  played  by  the  Note  Sequencer  as  though  it  were  an 
ordinary  note,  but  will  not  produce  a  tone.  You  can  therefore  use  filler  notes  to  fill  out 
rests  where  you  might  have  supposed  a  delay  would  be  needed.  For  example,  a  passage 
may  contain  a  chord  consisting  of  notes  with  different  duration,  followed  by  a  run  of 
other  notes.  In  this  case,  you  would  want  to  place  a  filler  note  at  the  end  of  the  chord,  so 
that  you  can  easily  vary  the  delay  between  the  start  of  the  chord  and  the  start  of  the  run. 


Filler  note  command 

volume 

0 

chord 
pitch 

1 

Pitch  value  =  0 

note 
duration 

1 

Desired  delay  time 

trk 
delay 

0 

Set  to  1  if  a  delay  is  desired 
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NoteOff  command 

volume  Note  volume-0 

chord  Set  if  the  note  is  part  of  a  chord 

pitch  0  to  127;  must  be  the  same  as  matching  NoteOn 

note  1 

duration  0 

trk  0-15;  must  be  the  same  as  matching  NoteOn 

delay  0 


NoteOn  command 


volume 

Note  volume;  varies  from  1  to  127 

chord 

Set  if  the  note  is  part  of  a  chord 

pitch 

Pitch  value;  varies  from  0  to  127 

note 

1 

duration 

0 

trk 

0-15 

delay 

0 
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Control  commands 

Control  commands  are  used  to  specify  the  characteristics  of  the  Note  Sequencer  as  it  is 
playing  the  notes.  They  can  control  pitch  bend,  tempo,  vibrato,  and  other  note 
characteristics. 


Figure  40-3      Control  command  format 


Bits 

3130 


27  26   24  23 


16  15  14 


d 

trk 

res 

val2 

n 

vail 

chord 

cmd 

cmd 
chord 

vail 
note 

val2 
reserved 

trk 

delay 


Command  number. 

The  chord  bit  should  be  set  to  1  in  a  control  command.  A  0  chord  bit 
can  sometimes  cause  unwanted  delays  in  playing  a  sequence. 

This  field  contains  data  specific  to  each  command. 

Always  set  this  bit  to  0  for  control  commands.  A  note  bit  set  to  1 
causes  the  seqltem  to  be  processed  as  a  note  command  instead  of  a 
control  command. 

Contains  data  specific  to  each  command. 

Reserved  for  control  field.  These  bits  should  always  be  set  to  0  unless 
otherwise  specified. 

Notes  are  assigned  to  synthesizer  voices  and  to  handlers  by  specifying 
their  trk  numbers.  Legal  values  are  $0  to  $F. 

The  delay  bit  should  always  be  set  to  0  in  control  commands,  since 
they  have  no  duration. 
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CallRoutine  command 


cmd 

30 

chord 

1 

vail 

0 

note 

0 

bits  16-23 

Low-order  byte  of  routine  address 

bits  24-31 

High-order  byte  of  routine  address 

This  command  allows  you  to  invoke  program  code  from  within  a  sequence  being  played 
by  the  Note  Sequencer.  This  program  code  is  then  free  to  perform  custom  processing.  The 
command  specifies  the  low-order  word  of  the  routine  address;  the  bank  portion  of  the 
address  matches  the  value  of  the  data  bank  register  at  the  time  the  Note  Sequencer  was 
started  by  your  application. 

On  entry,  interrupts  are  disabled  and  there  is  very  little  stack  space  remaining.  The  Note 
Sequencer  saves  its  registers  before  issuing  the  call.  However,  the  direct  page  and  data 
bank  registers  are  set  for  the  Note  Sequencer,  so  your  routine  code  must  change  these  in 
order  to  access  application  data.  The  routine  should  return  with  an  rtl  instruction. 

If  your  application  uses  MIDI,  this  routine  must  be  careful  to  poll  MIDI  every  270 
microseconds  to  avoid  losing  MIDI  data.  See  Chapter  38,  "MIDI  Tool  Set,"  in  this  book 
for  more  information. 
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Jump  command 


cmd 

3 

chord 

1 

vail 

vail  is  the  high  7  bits  of  the  destination 

note 

0 

val2 

vai2  is  the  low  8  bits  of  the  Jump  destination 

reserved 

0 

trk 

not  used 

delay 

0 

The  Jump  command  is  the  Note  Sequencer's  equivalent  of  a  jump  or  goto  command  in  a 
conventional  programming  language.  Execution  of  seqltems  will  continue  with  the  item 
specified  by  vail  and  vai2.  The  number  given  is  a  simple  index  into  the  series  of 
seqltems  (it  is  not  a  byte  index  into  the  seqltem  array).  The  Jump  command  does  not 
check  the  bounds  of  the  sequence,  and  it  is  therefore  possible  to  jump  to  an  arbitrary  area 
in  memory  that  does  not  contain  valid  seqltems,  which  will  produce  unpredictable  results. 

Note  that  this  command  causes  a  jump  in  the  sequence  being  processed.  To  jump  to 
executable  code  from  a  sequence,  use  the  CallRoutine  command. 
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Pitch  Bend  command 

cmd  0 

chord  1 

vail  Pitch  wheel  position.  Values  >  64  specify  sharp  pitch  bend;  values  <  64 

specify  flat;  intervals  are  expressed  in  fractions  of  the  current  pitch  bend 

range 
note  0 

vai2  No  significance  in  the  pitch  Bend  command;  the  val2  field  should  always 

be  set  to  0  for  Pitch  Bend 
reserved  Selects  pitch  bend  assignment 

0  selects  both  internal  and  MIDI  pitch  bend 

1  selects  internal  pitch  bend 

2  selects  MIDI  pitch  bend 
trk                     Track  number 

delay  0 

The  Pitch  Bend  command  creates  a  bend  effect  in  a  played  note.  A  control  command 
expresses  pitch  bend  as  a  value  from  0  to  127.  A  value  of  64  indicates  no  pitch  bend,  and 
the  note  is  played  at  the  pitch  specified  in  its  note  command.  The  note  is  played  at  a 
pitch  determined  by  its  nominal  pitch  plus  the  pitch  bend  sharp  or  flat.  The  pitch  changes 
immediately  to  the  new  value.  As  a  result,  the  sequence  must  use  a  series  of  Pitch  Bend 
commands  to  achieve  the  smooth  portamento  usually  associated  with  a  pitch  bend. 

The  reserved  field  indicates  whether  the  pitch  bend  is  to  affect  the  system's  internal 
voices,  external  MIDI  devices,  or  both.  Note  that  your  application  must  have  specified 
MIDI  support  at  Seqstartup  time  in  order  for  MIDI  commands  to  be  issued. 
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Program  Change  command 

cmd  5 

chord  1 

vail  Instrument  index  from  instalment  table 

note  0 

vai2  New  MIDI  program  number,  if  the  sequence  is  using  MIDI 

reserved  Specifies  MIDI  usage;  legal  values  are 

0  The  Apple  IIGS  internal  synthesizer  and  an  external  MIDI  device 

1  The  Apple  IIGS  internal  synthesizer  only 

2  External  MIDI  device  only 

trk  Track  number;  specifies  which  instrument  program  to  change  by 

specifying  the  track  to  which  that  instrument  is  assigned 
delay  0 

The  Program  Change  command  allows  a  sequence  to  change  the  instrument  assigned  to  a 
track  during  play.  The  new  instrument  must  be  in  the  current  instrument  table  for  the  new 
assignment  to  be  possible. 

If  MIDI  is  enabled  and  the  reserved  field  specifies  that  a  MIDI  command  is  to  be 
issued,  the  Note  Sequencer  generates  a  MIDI  Program  Change  command  using  vai2  for 
the  program  number. 


Tempo 

command 

cmd 

1 

chord 

1 

vail 

New  increment;  he  value  may  vary  from  0  to  127 

note 

0 

val2 

0 

reserved 

0 

trk 

0 

delay 

0 

This  command  sets  the  Note  Sequencer's  increment  value.  The  increment  value  determines 
the  number  of  ticks  between  updates  in  the  execution  cycle,  so  larger  increments  translate 
to  slower  tempos.  The  increment  value  is  set  to  its  initial  value  by  the  seqstartup  tool 
call. 
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Turn  Notes  Off  command 


cmd 

2 

chord 

1 

vail 

0 

note 

0 

val2 

0 

reserved 

0 

trk 

0 

delay 

0 

This  command  turns  off  all  notes  currently  being  played,  overriding  any  previous  note 
commands.  If  MIDI  support  has  been  enabled,  the  system  also  turns  off  any  active  MIDI 
notes. 


Vibrato  Depth  command 


cmd  4 

chord  1 

vail  The  new  value  for  vibrato  depth;  the  value  may  vary  from  0  to  127 

note  0 

vai2  Control  number  if  a  MIDI  command  is  generated 

reserved  0:  internal  and  MIDI  vibrato;  1:  internal  only 

trk  Track  number 

delay  0 

The  Vibrato  Depth  command  assigns  a  depth  value  to  the  vibrato  effect  used  with  the 
specified  track.  The  vibrato  effect  is  a  modulation  in  the  pitch  of  the  voice  assigned  to 
the  specified  track.  The  vail  value  can  range  from  0  to  127,  with  larger  values  resulting  in 
greater  vibrato  depth.  A  value  of  0  disables  vibrato,  which  conserves  CPU  cycles. 

If  MIDI  support  has  been  enabled  and  the  reserved  field  indicates  that  a  MIDI 
command  is  to  be  issued  as  well,  vai2  specifies  the  MIDI  control  number,  and  vail 
specifies  the  new  vibrato  value  for  the  MIDI  Control  Change  command. 
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Register  commands 

Register  commands  provide  the  Note  Sequencer  with  program  control  capabilities.  The 
Note  Sequencer  maintains  eight  8-bit  pseudoregisters  that  can  be  used  to  implement 
looping  and  conditional  branching  structures.  With  register  commands,  an  application  can 
achieve  the  effect  of  control  structures  such  as  "if... then,"  "do... while,"  or  "repeat... until" 
in  sequences. 

Each  register  occupies  8  bits  of  memory,  but  not  all  the  commands  use  the  full  register. 
The  IfGo  Register  and  Set  Register  commands  treat  each  register  as  if  it  were  only  4  bits  in 
size,  using  only  the  least  significant  4  bits  of  the  byte. 

Bytes  2  through  9  of  the  Note  Sequencer's  direct  page  contain  the  pseudoregisters;  these 
pseudoregisters  are  numbered  0  through  7.  Note  that  Note  Sequencer  direct-page  space 
starts  $100  bytes  beyond  the  location  specified  at  seqstartup  time.  The  intervening 
space  is  used  by  the  Note  Synthesizer  and  the  Sound  Tool  Set. 


Figure  40-4      Register  command  format 


Bits 

31  30 


2726   2423 


16  15  14 


d 

trk 

res 

val2 

n 

vail 

chord 

cmd 

cmd 
chord 

vail 

note 

val2 
reserved 

trk 


Command  number. 

The  chord  bit  should  be  set  to  1  in  a  register  command.  A  0  chord 
bit  can  sometimes  cause  unwanted  delays  in  playing  a  sequence. 

Contains  data  specific  to  each  command.  Generally  specifies  the 
register  number  for  the  command. 

Always  set  this  bit  to  0  for  register  commands.  A  note  bit  set  to  1 
causes  the  seqltem  to  be  processed  as  a  note  command  instead  of  a 
register  command. 

Contains  data  specific  to  each  command. 

Reserved  for  control  field.  These  bits  should  always  be  set  to  0  unless 
otherwise  specified. 

Always  set  to  0  for  register  commands. 
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delay  The  delay  bit  should  always  be  set  to  0  in  register  commands,  since 

they  have  no  duration. 


Dec  Register  command 


cmd 

9 

chord 

1 

vail 

Low  3  bits  contain  the  register  number 

note 

0 

val2 

0 

reserved 

0 

trk 

0 

delay 

0 

Decrements  the  value  of  the  specified  pseudoregister.  If  the  value  is  0  when  the  command 
is  executed,  the  pseudoregister's  value  will  wrap  to  $FF. 


IfGo  Register  command 


cmd 

7 

chord 
vail 

note 
val2 

1 

Low  3  bits  contain  the  register  number 

High  4  bits  contain  the  value 

0 

Offset:  -128  to  +127  seqltems 

reserved 

0 

trk 

0 

delay 

0 

Tests  the  specified  pseudoregister  for  the  specified  value.  If  the  pseudoregister  contains 
the  supplied  value,  then  execution  continues  with  the  seqltem  at  the  offset  specified  in 
vai2,  calculated  from  the  current  seqltem.  If  the  values  do  not  match,  execution 
continues  with  the  next  seqltem  in  sequence.  The  IfGo  Register  command  does  not  check 
the  bounds  of  the  offset  provided,  so  the  value  must  be  a  valid  one,  or  the  effects  will  be 
unpredictable. 
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Inc  Register  command 


cmd 

8 

chord 
vail 

1 

Low  3  bits  contain  the  register  number 

note 

0 

val2 

0 

reserved 

0 

trk 

0 

delay 

0 

Increments  the  value  of  the  specified  pseudoregister. 


Set  Register  command 

cmd  6 

chord  1 

vail  Low  3  bits  contain  the  register  number 

High  4  bits  contain  the  value 

note  0 

val2  0 

reserved  0 

trk  0 

d  0 

Sets  the  specified  pseudoregister  to  the  specified  value. 
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MIDI  commands 


MIDI  commands  enable  an  executing  sequence  to  send  data  direcdy  to  MIDI  devices  that 
are  connected  to  the  Apple  IIGS.  All  the  standard  MIDI  commands  are  provided. 

For  MIDI  commands  to  be  enabled,  the  high  bit  of  the  mode  parameter  must  be  set  when 
the  Seqs  tart  up  call  is  made.  To  produce  MIDI  output,  your  application  must  also  have 
loaded  and  started  up  the  MIDI  Tool  Set.  For  further  information  on  the  MIDI  Tool  Set, 
see  Chapter  38,  "MIDI  Tool  Set,"  in  this  book. 

These  commands  are  based  on  version  1.0  of  the  MIDI  specification,  version  1.0,  which  is 
not  described  in  this  documentation. 


■    Figure  40-5      MIDI  command  format 


Bits 

31 

24  23 

16 

15 

14 

8 

7 

6 

0 

high 

low 

n 

vail 

chord 

cmd 

cmd 
chord 

vail 
note 

low 
high 


Command  number. 

The  chord  bit  should  be  set  to  1  in  a  MIDI  command.  A  0  chord  bit 
can  sometimes  cause  unwanted  delays  in  playing  a  sequence. 

Contains  data  specific  to  each  command. 

Always  set  this  bit  to  0  for  MIDI  commands.  A  note  bit  set  to  1 
causes  the  seqltem  to  be  processed  as  a  note  command  instead  of  a 
MIDI  command. 

Contains  data  specific  to  each  command. 

Contains  data  specific  to  each  command. 
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MidiChannelPressure  command 

cmd  15 

chord  1 

vail  Bits  8  through  1 1  are  the  channel  number 

note  0 

low  Channel  pressure 

high  0 

Sends  a  MIDI  Channel  Pressure  command  to  the  channel  specified  in  vail.  The  new 
pressure  value  is  specified  by  the  low  byte. 


MidiControlChange  command 

cmd  13 

chord  1 

vail  Bits  8  through  11  are  the  channel  number 

note  0 

low  Control  number 

high  Control  value 

Sends  a  MIDI  Control  Change  command  to  the  channel  specified  in  vail.  The  control 
number  is  specified  in  the  low  byte  and  the  control's  new  value  is  in  the  high  byte. 


MidiNoteOff  command 


cmd  10 

chord  1 


vail  bits  8  through  11  are  the  channel  number 

note  0 

low  Note  number 

high  Velocity 

Sends  a  MIDI  NoteOff  command  on  the  channel  number  specified  in  vail.  The  note 
turned  off  is  specified  in  two  parts— a  note  number  in  the  low  byte  and  a  velocity  in  the 
high  byte. 
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MidiNoteOn  command 

cmd  11 

chord  1 

vail  Bits  8  through  11  are  the  channel  number 

note  0 

low  Note  number 

high  Velocity 

Sends  a  MIDI  NoteOn  command  on  the  channel  number  specified  in  vail.  The  note 
turned  on  is  specified  in  two  parts— a  note  number  in  the  low  byte  and  a  velocity  in  the 
high  byte. 


MidiPitchBend  command 

cmd  16 

chord  1 

vail  Bits  8  through  11  are  the  channel  number 

note  0 

low  Pitch  bend  least  significant  byte 

high  Pitch  bend  most  significant  byte 

Sends  a  MIDI  Pitch  Bend  command  to  the  channel  specified  by  vail.  The  new  pitch 
bend  value  is  specified  by  the  high  word  of  the  command,  with  the  least  significant  byte 
of  the  value  in  the  low  byte  and  the  most  significant  byte  in  the  high  byte. 
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MidiPolyphonicKeyPressure  command 


cmd 

12 

chord 

1 

vail 

Bits  8  through  11  are  the  channel  number 

note 

0 

low 

Note  number 

high 

Key  pressure 

Sends  a  MIDI  Polyphonic  Key  Pressure  command  on  the  channel  number  specified  in 
vail.  The  note  affected  is  specified  as  a  note  number  in  the  low  byte  of  the  high  word. 
Its  new  key  pressure  is  in  the  high  byte 


MidiProgramChange  command 


cmd 

14 

chord 

1 

vail 

Bits  8  through  11  specify  the  MIDI  channel  number  ($0-$0F) 

note 

0 

low 

Program  number 

high 

0 

Sends  a  MIDI  Program  Change  command  to  the  channel  specified  in  vail.  The  program 
number  is  specified  in  the  low  byte. 


MidiSelectChannelMode  command 

cmd  17 

chord  1 

vail  Bits  8  through  11  are  the  channel  number 

note  0 

low  First  data  byte 

high  Second  data  byte 

Sends  a  MIDI  Select  Channel  mode  command  to  the  channel  specified  in  vail.  The  new 
MIDI  channel  mode  is  specified  by  two  data  bytes,  the  first  of  which  is  passed  in  the  low 
byte  and  the  second  in  the  high  byte. 
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MidiSetSysExlHighWord  command 


cmd 

21 

chord 

1 

vail 

0 

note 

low 

high 

0 

Low  byte  of  high  word 

High  byte  of  high  word 

The  MIDI  System  Exclusive  command  passes  a  two-word  address  to  its  target.  That 
address  is  a  pointer  to  a  MIDI  packet.  The  high  word  of  the  address  is  specified  by  this 
command,  while  the  low  word  is  specified  by  the  MidiSystemExclusive  command.  The 
MidiSetSysExlHighWord  command  must  precede  the  MidiSystemExclusive  command. 
See  the  discussion  of  that  command  for  more  information  about  the  format  and  content 
of  the  MIDI  packet. 


MidiSystemExclusive  command 

cmd  18 

chord  1 

vail  0 

note  0 

low  Least  significant  byte  of  low  word  of  MIDI  packet  address 

high  Most  significant  byte  of  low  word  of  MIDI  packet  address 

The  MIDI  System  Exclusive  command  passes  a  two-word  address  to  its  target.  That 
address  is  a  pointer  to  a  MIDI  packet.  The  low  word  of  the  address  is  specified  by  this 
command,  while  the  high  word  is  specified  by  the  MidiSetSysExlHighWord  command. 
The  MidiSetSysExlHighWord  command  must  precede  the  MidiSystemExclusive 
command. 
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Here  is  an  example  of  a  3-byte  System  Exclusive  command. 


$00 

—               length               — 

$02 

timeStamp 

$06 

sysExclusive 

$07 

datal 

$08 

data2 

$09 

data3 

Word— Length  of  data  to  follow;  must  be  set  to  8 

j  4  Bytes— Time-stamp  for  send  time;  0  for  immediate  send 

Byte— System  Exclusive  flag  byte;  must  be  set  to  $F0 
Byte— First  MIDI  data  byte 
Byte— Second  MIDI  data  byte 
Byte— Third  MIDI  data  byte 


MidiSystemCommon  command 


cmd 

19 

chord 

1 

vail 

Bits  8  through  10— low  nibble  of  status  byte 

value  varies  from  1  through  7 

Bits  11  and  12— number  of  data  bytes: 

00  -  0  data  bytes 

01  - 1  data  byte 

10  -  2  data  bytes 

11  -  invalid  value 

note 

0 

low 

First  data  byte 

high 

Second  data  byte  (if  appropriate) 

Sends  one  or  two  bytes  of  MIDI  data.  The  first  data  byte  is  passed  in  the  low  byte  and 
the  second  data  byte,  if  there  is  one,  is  passed  in  the  high  byte. 
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MidiSystemRealTime  command 


cmd 

20 

chord 

1 

vail 

0 

note 
low 

0 

Real-time  number  ($01-$07) 

high 

0 

Sends  a  MIDI  System  Real-Time  command.  The  real-time  number  is  specified  in  the  low  3 
bits  of  the  low  byte. 
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Patterns  and  phrases 

A  pattern  is  any  series  of  seqltems.  The  Note  Sequencer  plays  melodies  by  carrying  out  the 
seqltem  commands  in  specified  patterns.  A  phrase  is  an  ordered  set  of  pointers  to 
patterns  or  to  other  phrases.  Since  a  phrase  can  contain  pointers  to  other  phrases,  it  is 
possible  to  nest  phrases.  The  Note  Sequencer  supports  up  to  12  levels  of  phrase  nesting. 

Phrases  and  patterns  have  a  similar  layout.  Both  phrases  and  patterns  are  preceded  by  a 
longword  header.  For  phrases,  this  header  is  set  to  1;  for  patterns,  the  header  is  set  to  0. 
The  Note  Sequencer  can  distinguish  between  phrases  and  patterns  by  examining  this 
header  value.  The  last  longword  in  both  phrases  and  patterns  must  be  set  to  $FFFFFFFF, 
and  is  called  the  phrase  done  flag. 

When  a  program  calls  the  Note  Sequencer  to  play  a  sequence,  it  passes  a  parameter 
containing  a  handle  to  the  first  byte  of  the  top-level  phrase.  This  phrase  consists  of  an 
ordered  series  of  pointers  to  the  patterns  or  phrases  to  be  played,  followed  by  a  longword 
value  ($FFFFFFFF)  that  marks  the  end  of  a  pattern  or  phrase. 

Each  pattern  consists  of  an  ordered  series  of  seqltems.  The  seqltems  describe  the 
characteristics  of  each  note  to  be  played  in  the  sequence.  Control  and  register  commands 
allow  the  characteristics  of  the  notes  to  be  modified  and  also  allow  the  programmer  to 
build  complex  sequences  by  using  conditional  looping  and  branching.  In  this  sense,  the 
Note  Sequencer  is  a  simple  programming  language. 

The  following  paragraphs  introduce  a  sample  phrase  and  a  sample  pattern,  so  that  you  can 
see  the  similarities  in  their  structure. 

A  phrase  is  identified  by  a  header  value  of  1 
topPhrase        dc  12 '0001*  ;    low  word 

dc  i2'0000'  ;    high  word 

The  phrase  body  consists  of  a  series  of  pointers.  Each  pointer  can  point  either  to  other 
phrases  or  to  patterns,  which  are  sequences  of  executable  seqltems.  For  example, 

dc    i4'phrasel' 

dc    i4'patternl' 

dc    i4'phrase2' 

A  phrase  always  ends  with  a  phrase  done  flag: 

dc     i4'$FFFFFFFF' 

A  pattern  is  identified  by  a  header  value  of  0 
patternl  dc  12' 0000'  ;    low  word 

dc  i2'0000'  ;    high  word 
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The  body  of  a  pattern  consists  of  seqltems,  such  as: 

dc  14' $880ABC74"  ;  play  C4,  duration=10,  volume=115 
dc  i4'$880ABE74 '  ;  play  D4,  duration=10,  volume=115 
dc     i4' $880AB074 '      ;  play  E4,  duration=10,  volume=115 

Again,  the  pattern  must  end  with  a  phrase  done  flag: 

dc     14'$FFFFFFFF' 
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A  sample  Note  Sequencer  program 

The  following  example  contains  65816  assembly  language  source  code  for  a  simple  Note 
Sequencer  program. 


mcopy 


s.m 


DPPointer 

gequ 

$10 

DPHandle 

gequ 

$14 

HelpingHand 

gequ 

$18 

******************************* 

Main 

Start 

Using 

Common 

clc 

xce 

long 

phk 

;  for  dereferencing  handles 


same 


plb 


; set  Native  mode 


; Set  the  data  bank  to  the 


;as  the  program  bank 


jsl 

StartTools 

jsl 

MakeWaves 

jsl 

Setlnstruments 

jsl 

PlaySequence 

jmp 

Cleanup 

StartTools 

_TLSta: 

ctUp 

;  Tool  Locator 

pha 

;  space  for  ID  returned 

_MMStartUp 

pi  a 

sta 

MylD 
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MakeWaves 


Trianglel 


PushLong 

#0 

PushWord 

#0 

PushWord 

#$600 

PushWord 

MylD 

PushWord 

#$C005 

PushLong 

#0 

_NewHandl 

e 

pla 

sta 

HelpingHand 

pla 

sta 

HelpingHand+2 

Ida 

[HelpingHand] 

sta 

DPPointer 

pha 

PushWord 

#0 

PushWord 

#0 

PushWord 

MylD 

_QDStartup 

PushLong 

#ToolTable 

_LoadTool 

s 

Ida 

DPPointer 

clc 

adc 

#$300 

pha 

Pushword 

#0 

Pushword 

#$200 

Pushword 

#$10 

_SeqStartup 

rtl 

ldx 

#0 

Ida 

#1 

sta 

SoundBuffer 

inx 

sta 

SoundBuf fer,x 

inc 

A 

cmp 

#$ff 

bne 

Trianglel 

;  Get  direct  page  for  tools 


;  direct  page 


;  either  320  or  640  mode 
;  max  size  of  scan  line 


;  QuickDraw  used  $300  bytes 


;  starts  Synth&Sound  Tools 


;  index  thru  SoundBuffer 

;  base  of  triangle 

;  step  thru  buffer 

;  slope  up  in  triangle 

;  byte  limit  for  sound  data 
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Triangle2 


mx 
dec 
sta 
emp 
bne 
inx 
sta 
inx 
sta 
inx 
sta 


SoundBuf f er , x 

#$01 

Triangle2 

SoundBuf fer,  x 

SoundBuf fer,x 

SoundBuf fer,x 


;  start  down  slope 


;  dont  want  zeros 


;  pad  3  bytes  with  1 


MakeTooth 
Sawtoothl 


ldy 
Ida 
inx 
sta 
dec 
bne 
dey 
bne 
Ida 
inx 
sta 
inx 
sta 


#2 
#$ff 

SoundBuf fer ,  x 

A 

Sawtoothl 

MakeTooth 
#1 

SoundBuf fer,  x 

SoundBuf fer,  x 


;  make  2  teeth 
;  start  high 


;  ramp  down 


;  do  2nd  tooth 


;  pad  last  2  bytes 


Squarel 


ldy 
Ida 
inx 
sta 
dey 
bne 


#255 
#1 

SoundBuf fer,  x 

Squarel 


;  make  a  square  wave 


Square2 


ldy 
Ida 
inx 
sta 
dey 
bne 


#255 
#255 

SoundBuf fer,  x 

Square2 
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Noisel 


NotZero 


ldy 

#256 

inx 

phy 

phx 

pha 

_Random 

pla 

bne 

NotZero 

inc 

A 

plx 

ply 

sta 

SoundBuf fer,: 

inx 

inx 

dey 

bne 

Noisel 

PushLong 

#SoundBuf fer 

PushWord 

#$100 

PushWord 

#$800 

WriteRamBlock 

;  noise  wave 


;  space  for  random  result 


;DOC  start  address 
;byte  count 


rtl 


Setlnstruments  Pushlong  #InstTableHandle 

_SetInstTabl 

ldx       #3 
TrackLoop      phx 

Pushword  #64 

phx 

phx 

_SetTrkInfo 

plx 

dex 

bpl       TrackLoop 

rtl 


;  do  4  tracks 


;  push  the  priority 
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PlaySequence 


PushLong   #0 
PushLong   #0 
PushLong   #Sequence 
_StartSeq 


;  No  Error  Handler  Routine 
;  No  Completion  Routine 


PushWord  #0 
PushWord  #0 
_ReadChar 
pla 


Pushword  #0 

_StopSeq 

rtl 


;  No  Next  Phrase 


Cleanup 


_SeqShutdown 
_EMShutdown 
_QDShutdown 
PushWord  MylD 
_DisposeAll 
Quit  QuitParams 


End 
**************************************************************** 

Common         Data 

QuitParams     dc        14' 0,0,0'      ;  Quit  back  to  calling  program 

MylD  ds        2 

tooltable      dc        i'2,26, 0,25, 0'  ;  two  tools,  numbers  26  &  25 

SoundBuffer   .  ds        2048 

InstTableHandle  dc  i4 ' InstTable' 

InstTable      dc   i2M' 

dc   i4' Sawtooth' 

dc   i4 ' Square1 

dc    i4 ' Triangle1 

dc   i4 ' Noise' 


4  waves,  512  bytes  each 
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Sawtooth 


segment 


Square 


segment 


dc 

il'127' 

dc 

il'0,127' 

dc 

il'120' 

dc 

11*20,1' 

dc 

il'120' 

dc 

il'0,0' 

dc 

il'O' 

dc 

il'60,12' 

dc 

il'O, 0,0* 

dc 

il'O, 0,0' 

dc 

il'O, 0,0' 

dc 

il'O, 0,0' 

dc 

il'3' 

dc 

il'32' 

dc 

il'2,80,90,0,1,1' 

dc 

il'127, 1,2, 6, 0,12* 

dc 

il'127, 1,2, 1,0, 12' 

dc 

il'127' 

dc 

il'0,127' 

dc 

il'120' 

dc 

il'20,1' 

dc 

il'120' 

dc 

il'0,0' 

dc 

il'O* 

dc 

il'60,12' 

dc 

il'O, 0,0' 

dc 

il'O, 0,0' 

dc 

il'O, 0,0' 

dc 

il'O, 0,0' 

dc 

il'3' 

dc 

il'32' 

dc 

il'2,80,90,0,1,1' 

dc 

il'127, 3, 2, 6, 0,12' 

dc 

il'127, 3, 2, 1,0, 12' 

envelope  breakpoint  1 

Increment  Value  1 

breakpoint  2 

increment  2 

sustain  at  120 

zero  increment  is  sustain 

release  to  0  volume 

slowly 

pad  with  extra  breakpoint 

increment  pairs  till  the 

total  is  8 

release  segment  is  3rd  segment 
priority  increment 
pbrange,vibdep, vibf , spare, A, B 
topkey, addr, size, Ctrl, pitch 
halt  b,  to  be  swapped  in  by  a. 

envelope  breakpoint  1 

Increment  Value  1 

breakpoint  2 

increment  2 

sustain  at  120 

zero  increment  is  sustain 

release  to  0  volume 

slowly 

pad  with  extra  breakpoint 

increment  pairs  till  the 

total  is  8 

release  segment  is  3rd  segment 
priority  increment 
pbrange, vibdep, vibf , spare, A, B 
topkey, addr, size, Ctrl, pitch 
halt  b,to  be  swapped  in  by  a. 
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Triangle 


segment 


Noise 


segment 


dc 

il'127' 

dc 

il'0,127' 

dc 

il'120' 

dc 

il'20,1' 

dc 

il'120" 

dc 

il'0,0' 

dc 

il'O' 

dc 

il'60,12' 

dc 

il'O, 0,0' 

dc 

il'0,0, 0' 

dc 

il'O, 0,0' 

dc 

il'O, 0,0' 

dc 

il'3' 

dc 

il'32' 

dc 

11*2,80,90,0,1,1' 

dc 

il'127, 5, 2, 6, 0,12' 

dc 

il'127, 5, 2, 1,0, 12* 

dc 

il'127' 

dc 

il'0,127' 

dc 

il'120' 

dc 

il'20,1' 

dc 

il'120' 

dc 

il'0,0' 

dc 

il'O' 

dc 

il'60,12' 

dc 

il'O, 0,0' 

dc 

il'O, 0,0* 

dc 

il'O, 0,0' 

dc 

il'O, 0,0' 

dc 

il'3' 

dc 

il'32' 

dc 

il'2,80,90,0,1,1* 

dc 

il'127, 7, 2, 6, 0,12' 

dc 

il'127, 7, 2, 1,0,12' 

;  envelope  breakpoint  1 

;  Increment  Value  1 

;  breakpoint  2 

;  increment  2 

;  sustain  at  120 

;  zero  increment  is  sustain 

;  release  to  0  volume 

;  slowly 

;  pad  with  extra  breakpoint 

;  increment  pairs  till  the 

;  total  is  8 

;  release  segment  is  3rd  segment 

;  priority  increment 

;  pbrange,vibdep, vibf , spare, A, B 

;  topkey,addr, size, ctrl, pitch 

;  halt  b,to  be  swapped  in  by  a. 

;  envelope  breakpoint  1 

;  Increment  Value  1 

;  breakpoint  2 

;  increment  2 

;  sustain  at  120 

;  zero  increment  is  sustain 

;  release  to  0  volume 

;  slowly 

;  pad  with  extra  breakpoint 

;  increment  pairs  till  the 

;  total  is  8 

;  release  segment  is  3rd  segment 

;  priority  increment 

;  pbrange, vibdep, vibf , spare, A, B 

;  topkey, addr, size, ctrl, pitch 

;  halt  b,  to  be  swapped  in  by  a. 
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Delay 

Tl 

T2 

T3 

TO 

Qtr 

Half 

Note 

C4 

D4 

E4 

F4 

G4 

Chord 


equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 


$80000000 

$08000000 

$10000000 

$18000000 

$0 

$40000 

$80000 

$8000 

$3C00 

$3E00 

$4100 

$4200 

$4300 

$80 


Sequence 
Phrasel 


dc 
dc 
dc 
dc 
dc 
dc 
dc 
dc 


i4'Phrasel' 
i4'l' 

i4'Phrase2' 
i4  'Patternl ' 
i4'Phrase2' 
14* Patternl' 
i4'Pattern2" 
i4*$FFFFFFFF" 


;  phrase  header 


terminator 


Phrase2 


dc 
dc 
dc 
dc 


i4'l' 

i4'Pattern2' 
i4' Patternl' 
i4'$FFFFFFFF' 


;  phrase  header 


;  terminator 


Patternl 


dc 
dc 
dc 
dc 
dc 
dc 


14' 0' 

i4 'Delay+T0+Qtr+Note+C4+127 ' 

14 ■ Tl+Qtr+Note+C4+Chord+127 ' 

i4 ' Delay+Tl+Qtr+Note+G4+127 ' 

i4 'Delay+T0+Half+Note+F4+127 ' 

i4'$FFFFFFFF' 


pattern  header 
full  volume 


terminator 
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Pattern2       dc  i4'0'  ;  pattern  header 

dc  i4'T2+Note+G4+Chord+127'  ;  note  on 

dc  i4'Note+Half '  ;  filler  note 

dc  i4'Delay+T2+Qtr+Note+F4+127' 

dc  i4'Delay+T3+Qtr+Note+D4+127' 

dc  i4'T3+Note+G4+Chord+127'  ;  note  off 

dc  i4'2'  ;  allnotesoff 

dc  i4'$FFFFFFFF'  ;  terminator 

End 
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Note  Sequencer  housekeeping  calls 

The  following  sections  discuss  Note  Sequencer  calls  that  perform  common  tool  set 
functions. 


SeqBootlnit     $011A 

Initializes  the  Note  Sequencer. 

▲  Warning       This  call  must  not  be  made  by  an  applications 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

C  extern  pascal  void  SeqBootlnit () ; 
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SeqStartUp    $021A 

SeqStartUp  starts  up  the  Note  Sequencer  and  performs  all  the  necessary  initializations  for 
the  tool  set.  It  also  makes  startup  calls  to  the  Sound  Tool  Set  and  the  Note  Synthesizer,  so 
an  application  should  not  start  up  those  tool  sets  before  making  this  call. 

Your  application  must  make  sure  that  the  MIDI  Tool  Set  has  been  started  before  issuing 
this  call. 

Parameters 

Stack  before  call 


Previous  contents 


dPageAddr 


mode 


updateRate 


increment 


Stack  after  call 


Word— Beginning  of  Note  Sequencer  direct  page 
Word— MIDI  flag 

Word— Rate  of  interrupt  generation 
Word— Number  of  interrupts  per  system  tick 
<— SP 


Previous  contents 


Errors 


$1A03 
$1A07 


<— SP 
startedErr 

nsWrongVer 


Sound  Tool  Set  errors 
Note  Synthesizer  errors 


The  Note  Sequencer  is  already 

started  up. 

The  Note  Synthesizer  is  a  version 

that  is  incompatible  with  the 

Note  Sequencer. 

Returned  unchanged 

Returned  unchanged 


extern  pascal  void  SeqStartUp (dPageAddr,  mode, 
updateRate,  increment)  ; 


Word 


dPageAddr,  mode,  updateRate,  increment; 
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dPageAddr  Specifies  the  location  for  the  Note  Sequencer's  direct  page.  This 

direct  page  must  actually  be  three  pages  of  bank  zero  memory, 
starting  at  the  specified  address.  The  first  page  is  used  by  the  Note 
Synthesizer  and  Sound  Tool  Set,  and  the  other  two  by  the  Note 
Sequencer.  All  three  pages  must  be  locked  and  page-aligned. 

mode  Determines  whether  the  Note  Sequencer  will  operate  in  interrupt 

mode,  in  which  updates  are  performed  automatically  as  interrupts 
occur,  or  in  step  mode,  in  which  updates  occur  only  when  explicit  step 
commands  are  issued.  If  the  low  bit  of  mode  is  set  to  0,  then 
interrupts  are  used;  if  it  is  set  to  1,  then  step  mode  is  used. 

The  high  bit  of  the  mode  parameter  also  determines  whether  MIDI 
processing  is  enabled.  If  an  application  uses  MIDI  commands  or  wants 
to  support  automatic  generation  of  appropriate  MIDI  commands, 
then  the  high  bit  must  be  set  to  1. 

updateRate  Specifies  how  often  the  Note  Sequencer  will  update  its  actions,  using 

interrupts.  For  example,  an  updateRate  value  of  500  specifies  that  the 
Note  Sequencer  will  receive  interrupts  at  200  hertz,  or  every  5 
milliseconds.  A  value  of  250  means  that  interrupts  will  be  available  at 
100  hertz,  or  every  10  milliseconds  (500  is  the  default  value)  The  same 
rate  is  used  by  the  Note  Synthesizer  to  update  its  instruments' 
envelopes. 

increment  Specifies  how  many  interrupts  constitute  one  tick  of  the  Note 

Sequencer  counter.  If  updateRate  is  500  and  increment  is  20,  then  one 
tick  will  take  100  milliseconds.  The  Note  Sequencer  gets  interrupts 
every  5  milliseconds,  and  the  counter  is  incremented  every  20 
interrupts.  If  a  quarter  note  equals  5  ticks,  then  it  lasts  half  a  second, 
which  corresponds  to  a  tempo  of  120  beats  per  minute.  In  general,  you 
can  compute  the  number  of  beats  per  minute  by  using  the  following 
formula: 

B  -  (24  •  updateRate)  I  {increment  *T) 

B  is  beats  per  minute  and  T  is  the  number  of  ticks  in  a  beat. 

Typical  updateRate  values  might  be: 

60  Hz  60/0.4  -  150;  updateRate  -  150 

100  Hz  100/0.4  -  250;  updateRate  =  250 

200  Hz  200/0.4  =  500;  updateRate  -  500 
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Larger  values  for  updateRate  result  in  greater  control  of  a  sequence's 
tempo  and  smoother  envelopes.  On  the  other  hand,  a  higher 
updateRate  also  requires  more  processor  time  to  service. 

One  general  method  for  choosing  appropriate  updateRate  and 
increment  values  is  to  decide  on  the  shortest  note  you  will  want  to 
play.  Suppose  the  shortest  note  that  you  want  to  play  is  a  sixteenth 
note.  Assign  sixteenth  notes  a  value  of  1.  Eighth  notes  are  twice  as 
long,  so  assign  them  a  value  of  2.  Quarter  notes  then  receive  a  value  of 
4,  half  notes  8,  and  whole  notes  16.  Now  decide  how  long  you  want  a 
whole  note  to  be  and  compute  the  updateRate  and  increment  so  that 
the  duration  comes  out  the  way  you  want  it. 

Once  you  have  set  the  updateRate  value,  it  remains  in  effect;  you  can 
only  change  it  by  making  the  Note  Synthesizer  NSSetupdateRate 
call,  or  by  shutting  down  and  restarting  the  Note  Sequencer.  You  can 
change  the  increment  value,  and  the  Note  Sequencer  provides  tempo 
calls  that  vary  the  tempo  for  you. 
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SeqShutDown     $031A 

Shuts  down  the  Note  Sequencer  tool  set.  It  frees  any  buffers  that  the  tools  may  have 
allocated.  An  application  that  uses  the  Note  Sequencer  should  call  SeqShutDown  before 
quitting. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1923        nsNotinit  The  Note  Synthesizer  has  not 

been  started. 

$1A05        nostartErr  The  Note  Sequencer  has  not  been 

started  up. 

$0812        noSAppmitErr  The  Sound  Tool  Set  was  not 

started  up. 

C  extern  pascal  void  SeqShutDown () ; 
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SeqVersion     $04lA 

Returns  the  version  number  of  the  Note  Sequencer  that  is  currently  in  use.  Refer  to 
Appendix  A,  "Writng  Your  Own  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference  for 
information  on  the  format  and  content  of  the  returned  versionNum  value. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


versionNum 


Errors 
C 


Word— Note  Sequencer  version  number 
<— SP 

None 

extern  pascal  Word  SeqVersion () ; 
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SeqReset     $051A 

Resets  the  Note  Sequencer.  SeqReset  is  called  when  the  Apple  IIGS  system  is  reset.  All 
internal  notes  presently  being  played  are  turned  off. 

▲  Warning       This  call  must  not  be  made  by  an  application.* 
Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

C  extern  pascal  void  SeqReset (); 
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SeqStatus     $06lA 

Returns  a  Boolean  flag  indicating  whether  or  not  the  Note  Sequencer  is  active.  If  the  tool 
set  is  active,  the  flag  is  nonzero;  otherwise  it  is  zero. 

♦   Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  SeqStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  the  Note  Sequencer  is  not  active,  the  returned  value  will 
be  FALSE  (NIL). 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


activeFlag 


Errors 
C 


None 


Word— Boolean;  TRUE  if  Note  Sequencer  is  active 
<— SP 


extern  pascal  Boolean  SeqStatus () 
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Note  Sequencer  calls 

The  following  sections  discuss  the  Note  Sequencer  tool  calls. 


Clearlncr     $0A1A 

Sets  the  Note  Sequencer's  increment  value  to  0,  halting  the  current  sequence,  and  returns 
the  previous  increment  value.  Setting  the  increment  to  0  does  not  disable  the  Note 
Sequencer's  interrupts,  so  envelopes  are  still  updated.  This  means  that,  although  the 
sequence  will  not  progress,  notes  being  played  when  the  increment  was  set  to  0  may  hang. 
This  call  is  valid  only  while  a  sequence  is  playing. 

You  might  try  using  seqAHNotesof  f  and  ciearincr  when  you  want  to  stop  a 
sequence  and  be  able  to  start  it  again  easily.  A  sequence  stopped  in  this  way  can  easily  be 
restarted  with  a  call  to  setincr. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


Result 


Errors 
C 


Word— Previous  increment  value 
<— SP 

None 

extern  pascal  Word  Clearlncr () ; 
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GetLoc     $0C1A 

Returns  certain  information  about  the  sequence  that  is  playing.  This  call  provides  an  index 
to  the  seqltem  that  is  executing,  the  current  pattern,  and  the  nesting  level.  The  nesting 
level  indicates  how  deeply  control  has  passed  into  a  structure  with  phrases  nested  within 
phrases.  A  nesting  level  value  of  0  indicates  that  the  Note  Sequencer  is  playing  the  top- 
level  phrase. 

For  example,  if  the  Note  Sequencer  is  playing  the  third  seqltem  in  Pattern  1,  which  occurs 
in  Phrase  1,  then  GetLoc  returns  this  information: 

curPattltem  =  3 
curPhraseltem  =  1 
curLevel  - 1 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Space 


Space 


Word— Space  for  result 
Word— Space  for  result 
Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


curPhraseltem 


curPattltem 


curLevel 


Errors 
C 


Word— Current  pattern  in  phrase  specified  by  curLevel 
Word — Current  seqltem  in  pattern  specified  by  curPhraseltem 
Word— Nesting  level  for  current  phrase 
<— SP 


None 

extern  LocRec  GetLoc (); 
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GetTimer    $0B1A 

Returns  the  value  of  the  Note  Sequencer's  tick  counter.  While  the  counter  is  advancing, 
the  value  returned  is  necessarily  somewhat  inexact,  since  the  value  changes  as  the  call  is 
executed.  The  call  is  valid  only  while  a  sequence  is  playing. 


Parameters 

Stack  before  call 

Previous  contents 

Space 

Word— Space  for  result 

<— SP 

Stack  after  call 

Previous  contents 

Result 

Word— Current  timer  value 

<— SP 

Errors                  None 

C 

exte 

rn  pascal  Word  GetTimer () 
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SeqAllNotesOff     $0D1A 

Switches  off  all  notes  that  are  playing,  but  does  not  stop  the  sequence.  Thus,  any  notes 
that  are  held  are  turned  off,  but  the  sequence  continues.  Use  this  call  to  temporarily 
silence  all  instrument  voices  while  a  sequence  is  active.  If  the  high  bit  of  the  mode 
parameter  is  set,  then  the  Note  Sequencer  also  turns  off  all  external  MIDI  notes  of  which  it 
is  aware. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  SeqAllNotesOff () ; 
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Setlncr     $091A 

Sets  the  Note  Sequencer's  increment  value.  An  application  can  use  this  facility  to  control 
the  tempo  of  a  sequence.  If  the  increment  value  is  set  to  0,  the  sequence  will  halt. 

Parameters 

Stack  before  call 


Previous  contents 


increment 


Stack  after  call 


Word— Desired  increment  value 
<— SP 


Previous  contents 


<— SP 

Errors       None 
C  extern  pascal  Setlncr (increment) ; 


Word 


increment; 
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SetlnstTable     $121A 

Sets  the  current  instrument  table  to  the  one  specified  in  instTable. 

Parameters 

Stack  before  call 


Previous  contents 


instTable 


Stack  after  call 


Long— Handle  to  instrument  table 
<— SP 


Previous  contents 


instTable 


<— SP 
Errors  None 

C  extern  pascal  void  SetlnstTable (instTable) ; 


Handle 


instTable; 


The  instTable  parameter  is  a  handle  to  an  instrument  table.  The 
instrument  table  is  a  data  structure  in  Apple  IIGS  memory  that 
contains  pointers  to  one  or  more  instruments.  The  format  of  an 
instrument  table  is  as  follows: 


$00 
$02 


instNumber       -   Word— Number  of  instalments  in  table 


instArray  '•  Array  oflongs — instNumber  pointers  to  instruments 


Note  that  the  first  pointer  in  the  array  corresponds  to  instrument  0. 
See  Chapter  41,  "Note  Synthesizer,"  in  this  book  for  more  information 
about  instruments. 
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SetTrklnfo     $0E1A 

Assigns  instruments  in  the  current  instrument  table  to  logical  tracks,  and  determines  the 
priorities  of  the  instruments  so  that  the  Note  Sequencer  an  correctly  allocate  generators 
to  them.  An  application  should  call  setTrkinf  o  for  each  track  it  uses,  before  starting  to 
play  a  sequence. 

If  MIDI  was  enabled  when  the  Note  Sequencer  was  started  up,  then  SetTrkinf  o  can  be 
used  to  enable  MIDI  output  on  particular  tracks.  If  the  most  significant  bit  of  the 
trackNum  parameter  is  set,  then  everything  played  on  the  specified  track  will  produce 
MIDI  output  on  the  channel  number  specified  by  the  second  most  significant  byte  of 
trackNum.  For  example,  a  trackNum  value  of  $8201  specifies  that  everything  played  on 
track  1  produces  MIDI  output  on  MIDI  channel  2. 

The  application  may  disable  the  internal  voices  of  the  Apple  IIGS  for  a  specified  track  by 
issuing  this  call  with  the  highest  bit  of  the  instlndex  parameter  set. 

You  must  make  a  setinstTabie  call  before  issuing  this  call. 

Parameters 

Stack  before  call 


Previous  contents 


priority 


instlndex 


trackNum 


Stack  after  call 


Word— Priority  value 

Word— Index  number  for  instrument  (first  instrument  is  number  0) 

Word— Track  number  for  instrument 

<— SP 


Previous  contents 


Errors 


$1A06 


<— SP 

instBndsErr 


The  specified  intrument  number 
is  out  of  the  bounds  of  the 
instrument  table. 


extern  pascal  void  SetTrklnfo (priority,  instlndex, 
trackNum) ; 


Word 


priority,  instlndex,  trackNum; 
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Startlnts     $131A 

Enables  interrupts.  Use  this  call  to  restore  normal  functioning  after  a  call  to  stopmts. 
Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal   Startlnts (); 
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StartSeq    $0F1A 

Starts  interpretation  of  a  series  of  seqltems  stored  at  the  address  specified  by  sequence. 

Parameters 

Stack  before  call 


Previous  contents 

Long— Pointer  to 

-  errHndlrRoutine 

error  handler 

-   compRoutine   - 

Long— Pointer  to 

Long— Handle  to 
<— SP 

completion  routine 

sequence 

sequence 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  $1921 

nSNoneAvail 

Note  Synthesizer  error:  no 
generator  is  available. 

$1AOO 

noRoomMidiErr 

The  Note  Sequencer  is  tracking 
32  notes  that  are  currently 
playing;  there  is  no  room  for  a 
MIDI  NoteOn. 

$1A01 

noCommandErr 

The  current  seqltem  is  not  valid 
in  its  context. 

$1A02 

noRoomErr 

The  sequence  is  nested  more  than 
twelve  levels  deep. 

$1A04 

noNoteErr 

Can't  find  the  note  for  a  NoteOff 
command. 

$1A05 

noStartErr 

The  Note  Sequencer  has  not  been 
started  up. 

$2004 

miToolsErr 

Required  tools  not  active  or 
wrong  version 

$2007 

miNoBufErr 

No  MIDI  output  buffer  is 

allocated. 
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errHndlrRoutine 


compRoutine 


sequence 


extern  pascal  void  StartSeq (errHndlrRoutine, 
compRoutine,  sequence) ; 

Pointer   errHndlerRoutine,  compRoutine; 
Handle    sequence; 

The  errHandlrRoutine  parameter  is  a  pointer  to  an  error  handling 
routine  supplied  by  the  application  programmer.  If  errHndlrRoutine  is 
set  to  NIL,  then  Note  Sequencer  will  not  invoke  a  routine.  For 
information  about  error  handling  routines  for  the  Note  Sequencer,  see 
"Error  handlers  and  completion  routines"  in  this  chapter. 

The  compRoutine  parameter  points  to  a  routine  to  be  called  when 
StartSeq  reaches  the  end  of  a  sequence.  If  compRoutine  is  set  to 
ML,  then  Note  Sequencer  will  not  invoke  a  routine.  For  information 
about  completion  routines  for  the  Note  Sequencer,  see  "Error  handlers 
and  completion  routines"  in  this  chapter. 

The  sequence  parameter  is  a  handle  to  the  phrase  to  be  executed  by 
the  Note  Sequencer.  The  handle  passed  in  sequence  should  be  locked. 
If  the  Note  Sequencer  is  running  in  interrupt  mode,  as  specified  by  the 
mode  parameter  of  the  seqstartup  call,  then  the  Note  Sequencer 
will  simply  start  interpreting  seqltems.  If,  however,  the  mode 
parameter  specified  that  the  Note  Sequencer  start  up  in  step  mode, 
then  the  start  seq  call  must  be  followed  by  a  series  of  calls  to 
stepseq  to  play  the  seqltems  individually. 
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StartSeqRel     $151A 

Starts  interpretation  of  a  series  of  seqltems  stored  at  the  address  specified  by  sequence. 
This  call  differs  from  startseq  in  that  it  uses  relative  addressing  from  the  beginning  of 
the  sequence.  That  is,  all  phrase  and  pattern  pointers  are  interpreted  as  offsets  from  the 
start  of  the  sequence,  rather  than  as  absolute  addresses.  As  a  result,  coding  phrases  and 
patterns  is  easier.  Following  the  call  description  you  will  find  a  code  sample  showing  how 
to  specify  these  relative  offsets. 

The  Note  Sequencer  uses  the  dereferenced  value  of  sequence  as  the  base  address  for  all 
phrases  and  patterns.  It  does  not  check  for  overflow,  and  does  not  support  negative 
offsets  from  the  specified  base  address. 

Parameters 

Stack  before  call 


Previous  contents 


-  errHndlrRoutine 


-    compRoutine   - 


sequence 


Long— Pointer  to  error  handler 

Long— Pointer  to  completion  routine 

Long— Handle  to  sequence 
<— SP 


Stack  after  call 


Previous  contents 


<— SP 
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Errors 


$1921    nSNoneAvail 


$1A00    noRoomMidiErr 


$1A01  noCommandErr 

$1A02  noRoomErr 

$1A04  noNoteErr 

$1A05  noStartErr 

$2004  miToolsErr 


$2007    miNoBufE 


rr 


Note  Synthesizer  error:  no 

generator  is  available. 

The  Note  Sequencer  is  tracking 

32  notes  that  are  currently 

playing;  there  is  no  room  for  a 

MIDI  NoteOn. 

The  current  seqltem  is  not  valid 

in  its  context. 

The  sequence  is  nested  more  than 

twelve  levels  deep. 

Can't  find  the  note  for  a  NoteOff 

command. 

The  Note  Sequencer  has  not  been 

started  up. 

Required  tools  not  active  or 

wrong  version 

No  MIDI  output  buffer  is 

allocated. 


errHndlrRoutine 


extern  pascal  void  StartSeqRel (errHndlrRoutine, 
compRoutine,  sequence) ; 

Pointer   errHndlerRoutine,  compRoutine; 
Handle    sequence; 

The  errHandlrRoutine  parameter  is  a  pointer  to  an  error  handling 
routine  supplied  by  the  application  programmer.  If  errHndlrRoutine  is 
set  to  NIL,  then  Note  Sequencer  will  not  invoke  a  routine.  For 
information  about  error  handling  routines  for  the  Note  Sequencer,  see 
"Error  handlers  and  completion  routines"  in  this  chapter. 

compRoutine        The  compRoutine  parameter  points  to  a  routine  to  be  called  when 
startseq  reaches  the  end  of  a  sequence.  If  compRoutine  is  set  to 
NIL,  then  Note  Sequencer  will  not  invoke  a  routine.  For  information 
about  completion  routines  for  the  Note  Sequencer,  see  "Error  handlers 
and  completion  routines"  in  this  chapter. 
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sequence  The  sequence  parameter  is  a  handle  to  the  phrase  to  be  executed  by 

the  Note  Sequencer.  The  handle  passed  in  sequence  should  be  locked. 
If  the  Note  Sequencer  is  running  in  interrupt  mode,  as  specified  by  the 
mode  parameter  of  the  seqstartup  call,  then  the  Note  Sequencer 
will  simply  start  interpreting  seqltems.  If,  however,  the  mode 
parameter  specified  that  the  Note  Sequencer  start  up  in  step  mode, 
then  the  startseq  call  must  be  followed  by  a  series  of  calls  to 
stepSeq  to  play  the  seqltems  individually. 
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Sample  sequence  with  relative  addressing 

The  following  example  is  a  sequence  presented  in  65816  assembly  language,  showing  how 
to  set  up  relative  addressing  for  startSeqRei. 

$80000000 

$08000000 

$18000000 

$40000 

$80000 

$8000 

$3C00 

$3E00 

$4100 

$4300 

$80 


Delay 

equ 

Tl 

equ 

T2 

equ 

qtr 

equ 

hlf 

equ 

Note 

equ 

C4 

equ 

D4 

equ 

F4 

equ 

G4 

equ 

Chord 

equ 

phrhndl 

dc 

phrl 

dc 

dc 

dc 

dc 

dc 

dc 

dc 

phr2 

dc 

dc 

dc 

dc 

patl 

dc 

dc 

dc 

dc 

dc 

dc 

14 ' phrl-phrhndl ' 
i4'01' 

i4'phr2-phrhndl' 
i4'patl-phrhndl' 
i4'phr2-phrhndl" 
i 4' patl -phrhndl' 
i 4' pat2 -phrhndl' 
i4'$FFFFFFFF' 

i4'01' 

i4'pat2-phrhndl' 
i4 ' patl-phrhndl ' 
i4'$FFFFFFFF' 


;  it ' s  a  phrase 


;  end  of  phrase  1 


it ' s  a  phrase 


end  of  phrase  2 


i4'00'  ;  it's  a  pattern 

i4 ' Delay+Tl+qtr+Note+C4+115 ' 
i4 • Tl+qtr+Note+C4+Chord+115 ' 
i4 'Delay+T2+qtr+Note+G4+115 ' 
i4 'Delay+Tl+hlf+Note+F4+115 ' 
i4'$FFFFFFFF'  ;  end  of  patl 
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pat2        dc  i4'00'  ;  it's  a  pattern 

dc  i4'Tl+Note+G4+Chord+115'       ;  NoteOn 

dc  i4'Note+hlfl  ;  filler  note 

dc  i4*Delay+T2+qtr+Note+F4+115' 

dc  i4'Delay+T2+qtr+Note+D4+115' 

dc  i4'Tl+Note+G4+Chord+115'       ;  NoteOff 

dc  14' $00000002'  ;  AllNotesOff 

dc  i4'$FFFFFFFF'  ;  end  of  pat2 
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StepSeq     $101A 


Increments  the  Note  Sequencer  counter,  causing  the  appropriate  seqltems  in  the  current 
sequence  to  be  processed.  A  stepSeq  call  is  the  equivalent  of  one  tick  of  the  Note 
Sequencer  counter,  which  consists  of  a  number  of  interrupts  equal  to  the  value  of  the 
increment  parameter  of  the  seqstartup  call. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 


Errors 


$1921  nSNoneAvail 

$1A01  noConimandErr 

$1A02  noRoomErr 

$1A04  noNoteErr 


Note  Synthesizer  error:  no 

generator  is  available. 

The  current  seqltem  is  not  valid 

in  its  context. 

The  sequence  is  nested  more  than 

twelve  levels  deep. 

Can't  find  the  note  for  a  NoteOff 

command. 


extern  pascal  void  StepSeq (); 
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Stoplnts     $141A 

Disables  Note  Synthesizer  and  Note  Sequencer  interrupts. 

If  the  Note  Sequencer  is  started  up,  and  interrupts  are  enabled,  the  Note  Synthesizer  calls 
the  Note  Sequencer  interrupt  handler  whenever  an  interrupt  occurs.  When  no  notes  are 
being  played,  the  overhead  involved  in  this  processing  is  unnecessary,  so  stoplnts 
provides  a  way  to  cause  the  Note  Synthesizer  not  to  service  the  interrupts.  To  restart 
interrupt  processing,  use  the  startints  call. 

The  startseq  call  starts  interrupt  processing  automatically,  and  the  seqShutDown 
automatically  halts  it.  No  other  Note  Sequencer  call  affects  interrupt  processing  except 
Stoplnts,  Startints,  and  SeqShutDown. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  Stoplnts (); 
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StopSeq     $111A 

Halts  interpretation  of  a  phrase.  The  next  parameter  specifies  whether  execution  should 
continue  if  there  are  more  phrases  to  be  executed  in  the  current  sequence.  If  so,  the  next 
phrase  begins.  Otherwise,  the  sequencer  simply  stops  and  calls  the  application's 
completion  routine.  See  "Error  handlers  and  completion  routines"  in  this  chapter  for  more 
information  on  completion  routines.  If  next  is  not  equal  to  0,  then  the  current  phrase 
terminates  and  execution  continues  with  the  next  phrase. 

If  any  notes  are  turned  on  with  NoteOn  commands,  and  a  call  to  stop seq  halts  the  phrase 
in  which  they  occur,  they  could  continue  to  play  forever,  waiting  for  NoteOff  commands 
that  will  never  occur.  You  should  thus  take  care  to  turn  off  any  such  notes  before  making  a 
call  to  StopSeq. 

Parameters 

Stack  before  call 


Previous  contents 


next 


Word— Boolean;  TRUE  to  process  remaining  phrases 
<— SP 


Stack  after  call 


Previous  contents 


<— SP 

Errors  None 

C  extern  pascal  StopSeq (next) ; 

Boolean   next; 
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Note  Sequencer  error  codes 

This  section  lists  the  error  codes  that  may  be  returned  by  Note  Sequencer  calls. 


Value 


Name 


Definition 


$1A00 


$1A01 
$1A02 

$1A03 
$1A04 
$1A05 
$1A06 

$1A07 


noRoomMidiErr 


noCommandErr 
noRoomErr 

startedErr 
noNoteErr 
noStartErr 
instBndsErr 

nsWrongVer 


The  Note  Sequencer  is  tracking  32  notes  that  are 

currently  playing;  there  is  no  room  for  a  MIDI 

NoteOn. 

The  current  seqltem  is  not  valid  in  its  context. 

The  sequence  is  nested  more  than  twelve  levels 

deep. 

The  Note  Sequencer  is  already  started  up. 

Can't  find  the  note  for  a  NoteOff  command. 

The  Note  Sequencer  has  not  been  started  up. 

The  specified  intrument  number  is  out  of  the 

bounds  of  the  instrument  table. 

The  Note  Synthesizer  is  a  version  that  is 

incompatible  with' the  Note  Sequencer. 
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Chapter  41   Note  Synthesizer 


This  chapter  documents  the  Note  Synthesizer.  This  is  new 
documentation,  not  previously  presented  in  the 
Apple  1IGS  Toolbox  Reference. 
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About  the  Note  Synthesizer 

The  Note  Synthesizer  is  a  tool  set  that  controls  operation  of  the  Apple  IIGS  Digital 
Oscillator  Chip  (DOC).  With  it,  an  application  can  turn  the  Apple  IIGS  into  a  digital 
synthesizer  for  playing  music  and  generating  sound  effects.  The  Note  Synthesizer 
provides  far  more  control  over  a  sound  than  the  Sound  Tool  Set,  and  supports  looping 
within  a  sound  sequence  and  enveloping  a  sound. 


Using  the  Note  Synthesizer 

An  application  that  uses  the  Note  Synthesizer  must  first  start  it  up  and  write  the  wave 
information  to  the  DOC  RAM  by  using  the  Sound  Tool  Sefs  writeRAMBiock  call,  then 
allocate  Digital  Oscillator  Chip  generators  for  its  use  with  AiiocGen.  It  can  play  musical 
notes  with  individual  calls  to  NoteOn  and  NoteOf  f  for  each  note  that  it  plays.  NoteOn 
starts  a  generator  and  the  process  that  automatically  updates  envelopes  as  it  plays  its 
assigned  instrument.  When  the  application  calls  Noteof  f ,  the  Note  Synthesizer  enters  the 
release  phase  of  the  envelope  for  that  generator,  and  the  note  begins  to  die  away. 

The  Note  Synthesizer  requires  that  the  Sound  Tool  Set  be  loaded  and  started  up. 


The  sound  envelope 

The  envelope  describes  the  graph  of  a  sound's  loudness  over  time.  The  terms  loudness, 
amplitude,  and  volume  all  refer  to  the  same  characteristic  of  a  sound.  In  addition,  the 
MIDI  quantity  velocity  is  normally  mapped  to  a  note's  loudness,  so  that,  for  instance,  the 
faster  a  key  on  a  keyboard  is  struck,  the  louder  its  corresponding  note  will  be.  A  note's 
envelope  is  what  gives  it  its  dynamic  quality.  A  short,  sharp  sound  has  a  steep,  short 
envelope,  and  a  long,  smooth  sound  has  a  flatter,  longer  envelope. 

A  synthesizer's  envelope  is  traditionally  described  in  terms  of  attack,  decay,  sustain,  and 
release,  or  ADSR.  Figure  41-1  shows  an  example  of  a  simple  envelope  described  in  terms 
of  ADSR. 


41-2      Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Figure  41-1      Sound  envelope,  showing  attack,  decay,  sustain,  and  release 


The  attack  portion  of  an  envelope  is  the  period  when  the  sound  is  increasing  from  silence 
to  its  peak  loudness.  This  part  of  the  envelope  determines  the  suddenness  of  a  sound.  A 
drumbeat  or  a  plucked  string  has  an  extremely  steep  attack,  whereas  a  bowed  string  or  a 
softly  blown  wind  instrument  has  a  much  flatter  attack. 

The  decay  part  of  the  envelope  is  the  period  when  the  sound  falls  off  from  its  peak 
loudness  to  the  level  it  stays  at,  which  is  its  sustain  portion.  Attack  and  decay  together 
can  be  used  to  control  a  sound's  percussiveness.  Sounds  with  a  steep  attack  and  decay 
tend  to  sound  plucked  or  percussive.  A  steep  attack  followed  by  a  flat  decay,  or  by  little 
or  no  decay,  blares  like  a  loud  trumpet.  A  very  flat  attack  and  decay  produce  a  sound  with 
a  soft,  smooth  quality. 

Sustain  determines  the  note's  overall  perceived  loudness  and  duration.  A  drumbeat  has 
virtually  no  sustain  or  release;  it  consists  almost  entirely  of  attack  and  decay.  A  long,  slow 
note  on  a  violin,  on  the  other  hand,  might  have  a  very  flat  attack  and  decay,  and  a  long, 
high  sustain. 

The  release  is  the  portion  of  a  note  as  it  dies  away.  Long  releases  can  produce  a  nice 
ringing  quality,  but  can  also  be  a  problem  if  a  note  is  still  sounding  when  another  note 
starts  and  is  dissonant  with  the  first  note. 
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Note  Synthesizer  envelopes 

The  envelope  definition  in  the  Note  Synthesizer's  instrument  record  is  somewhat  more 
complex  than  this  simple  four-part  scheme.  The  instrument's  envelope  field  can  specify  up 
to  eight  segments  instead  of  just  four,  so  more  complex  sequences  of  attack,  decay, 
sustain,  and  release  are  possible.  For  example,  the  physical  properties  of  pianos  cause 
them  to  have  a  complex  envelope  with  two  attack  segments.  A  simple  ADSR  is  therefore 
limited  in  its  ability  to  simulate  a  piano's  envelope.  The  Note  Synthesizer  can  do  better, 
because  its  eight  envelope  segments  allow  a  closer  approximation  of  the  piano's  actual 
envelope. 

Figure  41-2  shows  an  envelope  created  with  eight  envelope  segments. 


Figure  41-2      Typical  Note  Synthesizer  envelope 


An  instrument's  envelope  definition  is  composed  of  up  to  eight  linear  segments.  During 
each  segment,  the  note's  loudness  slopes  from  its  starting  value  toward  its  defined 
breakpoint  value.  The  segments  are  defined  as  a  series  of  breakpoints  and  increments. 

The  breakpoint  respresents  the  loudness  of  the  sound  in  a  byte  value  between  0  and  127 
on  a  logarithmic  loudness  scale.  A  value  difference  of  16  represents  a  change  of  6  decibels 
in  loudness. 
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The  increment  determines  the  amount  of  time  to  be  spent  reaching  the  breakpoint 
volume.  The  value  is  a  2-byte  fixed-point  number  which  indicates  the  amount  by  which  the 
current  volume  is  to  be  adjusted  at  each  update  (the  default  rate  is  100  updates  per 
second;  you  can  set  other  values  with  the  Nsstartup  and  NSSetupdateRate  tool 
calls).  The  low-order  byte  contains  the  numerator  for  a  fractional  increment.  For  example, 
an  increment  value  of  1  translates  to  a  fractional  increment  of  V4*.  In  this  case,  the  volume 
will  be  incremented  once  every  256  interrupts.  The  Note  Synthesizer  will  process  the 
segment  until  its  volume  reaches  the  specified  breakpoint  value,  at  which  time  it  moves 
to  the  next  segment. 

The  shape  of  the  envelope  is  arbitrary;  it  can  be  any  shape  that  can  be  specified  in  eight 
segments,  so  complex  envelopes  are  possible.  The  last  breakpoint,  though,  should  always 
be  0,  so  that  the  note  dies  away  at  the  end.  The  volume  should  not  go  to  0  before  the  end 
of  the  segment  or  the  sound  is  considered  done. 

The  length  of  time  that  a  segment  of  the  envelope  lasts  is  given  by  the  following  formula: 

_  l(L-N)l«256 
*  (0.4>(1*R) 


where 

T  -  segment's  duration 
L  -  last  breakpoint 
N  -  next  breakpoint 
I  -  increment  value 
R  -  update  rate' 

As  an  example,  for  a  segment  that  changes  from  30  to  40  with  an  increment  value  of  25  and 
an  update  rate  of  100  cycles  per  second,  the  formula  becomes 


10040)1*256  2560 


(0.4X25*100)       (0.4)2500 


2.56  seconds 


Thus,  with  the  given  parameters,  the  specified  segment  will  last  2.56  seconds. 
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The  increment  value  of  a  sustain  segment  is  0,  so  the  previous  formula  cannot  be  used  to 
calculate  the  duration  of  the  sustain  portion  of  an  envelope.  Instead,  the  sustain  portion 
simply  continues  until  a  release  is  signaled.  If  the  release  portion  of  the  note  sustains,  then 
the  note  will  continue  to  be  played  until  there  are  no  available  generators  left,  and  the 
generator  producing  the  note  is  reallocated  to  another  note. 


Instruments 

The  Note  Synthesizer's  basic  functional  unit  is  an  instrument  This  is  a  data  structure 
stored  somewhere  in  the  memory  of  the  Apple  IIGS  that  defines  the  sound  characteristics 
of  a  played  note.  When  a  program  makes  the  Noteon  call,  it  passes  a  pointer  to  an 
instrument,  and  that  instrument  is  used  while  generating  the  sound.  Figure  41-3  shows  the 
format  of  the  instrument  data  structure. 


Figure  41-3      Instrument  data  structure 


$00 

j 

envelope 

$18 

releaseSegment 

$19 

priority Increment 

$1A 

pitchbendRange 

$1B 

vibratoDepth 

$1C 

vibratoSpeed 

$1D 

Spare 

$1E 

aWaveCount 

$1F 

bWaveCount 

$20 

aWaveList 

$xx 

bWaveList 

i 

24  Bytes 

Byte 
Byte 
Byte 
Byte 
Byte 
Byte 
Byte 
Byte 

.'  aWaveCount  Wave  entries 


:  bWaveCount  Wave  entries 
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envelope  Specifies  the  envelope  for  the  sound,  as  a  series  of  8  segments,  each  a 

breakpoint  and  increment  value  pair  (see  "Note  Synthesizer 
envelopes"  in  this  chapter  for  detailed  information  on  these 
concepts).  Each  breakpoint  is  a  one-byte  value  specifying  a  target 
volume  level  in  the  range  from  0  through  127.  Each  increment  is  a 
two-byte  value  which  determines  the  amount  of  time  the  Note 
Synthesizer  will  spend  reaching  the  breakpoint  volume. 

The  envelope  array  has  the  following  format: 


$00 

breakpoint!) 

$01 
$03 

—    incrementO    — 

breakpointl 

$04 

—    incrementl    — 

$15 

breakpoint 7 

$16 

—    increment7    — 

Byte-^Breakpoint  value  for  segment  0 
Word— Increment  value  for  segment  0 
Byte— Breakpoint  value  for  segment  1 
Word— Increment  value  for  segment  1 


Byte— Breakpoint  value  for  segment  7 
Word— Increment  value  for  segment  7 


releaseSegment 


Defines  the  segment  at  which  release  begins  when  a  NoteOf  f  call  is 
made.  Its  value  can  be  any  number  from  0  to  7,  and  identifies  which 
segment  in  sequence  is  the  beginning  of  the  release  phase  of  the 
envelope.  The  release  portion  may  thus  occupy  several  segments,  but 
the  last  breakpoint  should  always  be  0.  For  example,  if 
releaseSegment  is  set  to  5  and  breakpoint?  has  a  value  of  0,  the 
Note  Synthesizer  ramps  through  segments  5,  6,  and  7  before  shutting 
down. 
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prioritylncrement 

Subtracted  from  the  generator's  priority  value  when  the  envelope 
reaches  its  sustain  phase.  The  Note  Synthesizer  uses  the  changing 
priority  values  to  reallocate  generators,  giving  higher  priority  to  notes 
that  are  just  starting.  When  an  envelope  reaches  the  release  portion, 
the  priority  value  assigned  to  its  generator  is  again  reduced,  this  time 
to  half  its  current  value.  Thus,  the  higher  priorities  go  to  notes  that  are 
just  starting;  notes  being  sustained  are  accorded  lower  priority,  and 
notes  in  their  release  phase  receive  lowest  priority.  This  is  just  a  rule  of 
thumb;  the  actual  priority  values  depend  on  the  priority  that  was 
specified  when  the  generator  was  allocated.  For  more  information  on 
generator  priorities,  see  "Generators"  in  this  chapter. 


pitchbendRange 

Specifies  the  maximum  pitch  bend  that  is  possible  on  the  note.  The 
maximum  possible  value  for  a  pitch  bend  is  127;  pitchbendRange 
specifies  by  how  many  semitones  the  pitch  is  raised  with  the  pitch 
bend  value  of  127.  The  legal  values  are  1, 2,  and  4  semitones.  Note  that 
the  only  way  to  change  the  pitchbend  value  for  a  note  that  is  playing  is 
to  change  the  pitchbend  field  of  the  appropriate  Generator  Control 
Block  (GCB)  (see  "Generators"  in  this  chapter  for  information  on  the 
format  and  content  of  the  GCB). 

The  pitchbend  field  is  mainly  used  by  the  Note  Sequencer.  It  is 
possible  to  set  its  value  directly,  but  it  is  normally  used  by  the  Note 
Sequencer  to  pass  information  to  the  Note  Synthesizer  about  how  to 
play  notes  in  a  sequence. 

vibratoDepth    Any  number  from  0  to  127.  A  depth  of  0  specifies  that  there  is  no 
vibrato  effect  on  the  note.  Vibrato  is  produced  by  modulating  the 
pitch  of  the  two  oscillators  that  make  up  a  generator,  using  a  triangle 
wave  produced  by  a  Low  Frequency  Oscillator  (LFO).  When  the 
vibratoDepth  parameter  specifies  that  there  is  to  be  no  vibrato 
effect,  the  vibrato  software  is  switched  off  to  save  processing  time, 
because  the  processing  required  to  create  the  triangle  wave  can 
consume  a  large  amount  of  processor  time. 

vibratospeed    Controls  the  rate  of  vibrato.  Higher  values  produce  faster  vibrato.  The 
actual  speed  of  vibrato  effect  depends  on  the  update  rate,  which 
defaults  to  100  updates  per  second.  You  can  set  other  rates  with  the 
NSStartUp  and  NSSetUpdateRate  tool  calls. 
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aWaveCount,  bWaveCount 

Specify  the  number  of  waves  in  the  wavelists  that  follow  the 
wavecounts.  The  Note  Synthesizer  can  use  sampled  or  artificially 
created  waveforms  to  produce  its  notes. 

aWaveList,  bWaveList 

A  wavelist  is  an  array  of  variable  length.  The  elements  of  the  array  are 
6-byte  structures  A  wavelist  can  contain  up  to  255  entries. 

An  entry  in  a  wavelist  data  structure  specifies  wave  data  that  is 
intelligible  for  the  DOC.  The  Note  Synthesizer  places  the  data  into  the 
DOC  registers. 


$00 

topKey 

Byte 

$01 

waveAddress 

Byte 

$02 

waveSize 

Byte 

$03 

DOCMode 

Byte 

$04 

—             relPitch             — 

Word 

topKey 


waveAddress 


waveSize 


When  the  Note  Synthesizer  plays  a  note,  it  examines  the  topkey 
field  of  each  waveform  in  the  wavelists  until  it  finds  a  value  that 
is  greater  than  or  equal  to  the  value  of  the  note  it  is  attempting 
to  play.  The  first  waveform  it  finds  with  an  acceptable  topkey 
value  is  the  one  it  plays.  For  this  reason,  waveforms  should  be 
stored  in  increasing  order  of  topkey  value.  The  last  waveform  in 
a  wavelist  should  have  a  value  of  127,  the  maximum  valid  pitch 
value. 

The  waveAddress  parameter  is  the  high  byte  of  the  waveform's 
address  in  Sound  RAM.  Its  value  is  copied  into  the  Address 
Pointer  register  of  the  DOC. 

The  waveSize  parameter  sets  the  size  of  the  DOC's  wave  table, 
and  the  frequency  resolution  of  the  DOC.  This  parameter  is 
copied  directly  to  the  DOC's  Bank-Select/TableSize/Resolution 
register.  The  resolution  and  table  size  should  normally  be  equal. 
See  Chapter  47,  "Sound  Tool  Set  Update,"  in  this  book  and  the 
Apple  IIGS  Hardware  Reference  for  more  information. 
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DOCMode  The  DOCMode  parameter  sets  the  mode  of  the  Digital  Oscillator 

Chip.  This  parameter  corresponds  to  the  Control  register  of  the 
DOC,  and  supplies  the  stereo  position  of  the  oscillator.  Bit  3  of 
this  register  (the  interrupt  enable  bit  for  the  DOC)  should  always 
be  set  to  0.  See  Chapter  47,  "Sound  Tool  Set  Update,"  in  this 
book  and  the  Apple  IIGS  Hardware  Reference  for  more 
information. 

reiPitch  The  reiPitch  parameter  is  a  word  value  that  is  used  to  tune  the 

waveform.  The  high-byte  value  is  the  semitone,  and  the  low  byte 
is  fractions  of  semitones.  A  value  of  1  in  the  low  byte 
corresponds  to  Vfcof  a  semitone.  A  wavelist  can  specify  a  full 
range  of  notes  for  an  instrument  with  entries  for  each  note  that 
differ  only  in  the  reiPitch  field.  Such  a  wavelist  would  specify 
an  instrument  whose  timbre  is  the  same  for  every  note;  only  the 
pitch  is  different. 

For  more  information  on  DOC  registers  and  waveforms,  see 

Chapter  47,  "Sound  Tool  Set  Update,"  in  this  book  and  the  Apple  IIGS  Hardware  Reference. 


DOC  memory 

One  page  of  bank  zero  memory  must  be  allocated  to  the  Sound  Tool  Set  for  use  as  a 
direct  page.  The  Note  Synthesizer  shares  this  direct-page  space  with  the  Sound  Tool  Set. 

An  application  that  uses  the  Note  Synthesizer  must  load  any  waveforms  that  it  can  use 
into  DOC  memory  with  the  Sound  Tool  Set  call  writeRAMBiock.  You  must  not  place  a  0 
in  the  first  256  bytes  of  DOC  memory  because  it  halts  the  timer  oscillator;  this  will  cause  a 
system  failure.  If  the  application  uses  the  clock  function  of  the  MIDI  tools,  then  it  must 
not  write  to  the  first  256  bytes  of  DOC  memory. 


Generators 

Each  generator  is  a  pair  of  DOC  oscillators.  There  are  32  such  oscillators;  two  of  them  are 
reserved  for  the  use  of  Apple  Computer,  Inc.  The  remaining  30  are  paired  into  15 
generators  for  the  Note  Synthesizer.  The  Note  Synthesizer  uses  one  of  these  generators  as 
a  timer,  leaving  14  generators  for  general  use.  If  the  MIDI  Tool  Set  is  started  up  and  is 
using  the  MIDI  clock  function,  another  generator  is  allocated  to  serve  as  the  MIDI  clock, 
leaving  13  general-purpose  generators  for  application  use. 
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The  Note  Synthesizer  allocates  generators  to  all  the  different  sound  tools  that  may  need 
them.  It  therefore  requires  a  priority  scheme  for  allocating  generators  in  the  event  that  a 
generator  is  requested  when  all  generators  are  in  use.  When  a  generator  is  allocated,  it 
receives  a  priority.  A  generator's  priority  may  range  from  0  through  128.  A  priority  of  0 
means  the  generator  is  not  being  used  and  will  be  allocated  to  any  use  that  requests  it.  A 
priority  of  128  indicates  that  the  generator  is  locked  and  cannot  be  reallocated.  The 
remaining  values  in  a  generator's  range  are  used  by  the  Note  Synthesizer  to  control 
allocation  of  generators. 

The  Note  Synthesizer  automatically  lowers  the  priority  of  a  generator  that  has  reached  the 
sustain  portion  of  its  envelope,  and  lowers  it  again  when  it  reaches  the  release  portion. 
When  the  note  stops,  the  generator's  priority  becomes  0.  An  application  specifies  a 
priority  when  requesting  allocation  of  a  generator,  so  that  allocation  occurs  when  a 
generator  is  available  with  a  priority  lower  than  that  requested. 

The  Note  Synthesizer  divides  its  direct-page  area  into  15  blocks  of  16  bytes,  called 
generator  control  blocks  (GCB).  The  GCB  contains  the  values  of  any  "knobs"  or 
"controllers"  affecting  the  parameters  of  the  note  that  it  is  currently  playing.  A 
programmer  normally  should  not  access  the  GCB. 

Figure  41-4  shows  the  format  and  content  of  the  GCB. 
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Figure  414      Generator  control  block 


$00 

synthID 

$01 

genNum 

$02 

semitone 

$03 

volume 

$04 

pitchbend 

$05 

vibratoDepth 

$06 

Reserved      ■ 

i 

Byte— Identifies  user  of  generator 

Byte— Identifies  the  generator  itself 

Byte— Note  currently  being  played  by  the  generator 

Byte— Output  volume  for  current  note 

Byte— Pitchbend  value  for  current  note 

Byte— Vibrato  for  current  note 

10  Bytes— Note  Synthesizer  and  Sound  Tools  reserved 


synthID 

0 

1 

2 

3 

4 

5-7 

8-15 

genNum 


semitone 


volume 


pitchbend 


Identifies  who  is  currently  using  the  generator.  Valid  values  are 

Not  used 

Sound  Tool  Set  freeform  synthesizer 

Note  Synthesizer 

Reserved  for  use  by  Apple  Computer,  Inc. 

MIDI  Tool  Set 

Reserved  for  use  by  Apple  Computer,  Inc. 

User  defined 

Uniquely  identifies  the  generator.  Valid  values  lie  in  the  range  from  0 
through  13  ($00  through  $0D).  Your  application  uses  this  value  to 
identify  a  specific  generator  to  the  Note  Synthesizer.  The  tool  set 
returns  the  identifier  on  the  AiiocGen  call. 

Identifies  the  note  currently  being  played.  Contains  a  standard  MIDI 
value  in  the  range  from  0  to  127,  where  middle  C  has  a  value  of  60. 

Identifies  the  output  volume  for  the  current  note  specified  by 
semitone.  Valid  values  lie  in  the  range  from  0  through  127,  and 
correspond  to  MIDI  velocity.  A  16-step  change  in  volume 
corresponds  to  a  6  decibel  change  in  amplitude. 

Identifies  pitch  bend  to  be  applied  to  the  note  specified  by 
semitone.  Valid  values  lie  in  the  range  from  0  through  127;  a  value  of 
64  specifies  no  pitch  bend.  The  pitchbendRange  field  of  the 
instrument  record  (see  "Instruments"  earlier  in  this  chapter)  specifies 
the  maximum  allowable  pitch  bend,  in  semitones. 


41-12     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  1IGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


vibratoDepth 


Reserved 


Specifies  the  depth  of  vibrato  for  the  note.  Valid  values  lie  in  the 
range  from  0  through  127.  A  value  of  0  indicates  no  vibrato  (this  is  the 
recommended  value).  A  value  of  127  yields  maximum  vibrato  depth. 

Area  reserved  for  internal  use  by  the  Note  Synthesizer  and  the  Sound 
Tool  Set. 
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Note  Synthesizer  housekeeping  calls 

All  the  call  descriptions  for  the  Note  Synthesizer  are  new.  The  tool  calls  were  not  previously 
documented  in  the  Apple  IIGS  Toolbox  Reference. 


NSBootlnit     $0119 

Initializes  the  Note  Synthesizer. 

▲  Warning       An  application  must  not  make  this  call.  ▲ 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  NSBootlnit () ; 
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NSStartUp     $0219 

Starts  up  the  Note  Synthesizer  for  use  by  an  application.  An  application  must  make  this 
call  before  it  makes  any  other  Note  Synthesizer  calls  except  Nsstatus  orNSVersion. 
The  updateRate  parameter  specifies  the  rate  at  which  interrupts  are  generated  to  update 
envelopes  and  low-frequency  oscillations.  The  value  is  in  units  of  0.4  Hz.  Reasonable 
values  for  this  parameter  include  150,  250,  and  500.  The  default  value  is  500.  Low  rates 
require  less  overhead,  but  higher  rates  generate  smoother  sounding  envelopes. 

The  userUpdateRtn  parameter  is  a  pointer  to  a  routine  that  is  called  during  every  timer 
interrupt.  Sequencer  programs  are  an  example  of  software  that  might  use  routines  that  run 
during  Note  Synthesizer  interrupts,  and,  in  fact,  this  is  how  the  Note  Sequencer  works.  A 
value  of  0  indicates  that  there  is  no  user  update  routine. 


Parameters 

Stack  before  call 

Previous  contents 

updateRate 

Word— Rate  of 

-  userUpdateRtn  - 

Long— Pointer  t 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  $1901 

nsAlreadylnit 

$1902 

nsSndNotlnit 

$1925 

soundWrongVer 

Note  Synthesizer  already  started 

up. 

Sound  Tool  Set  not  started  up. 

Incompatible  version  of  Sound 

Tool  Set. 


extern  pascal  void  NSStartUp (updateRate, 
userUpdateRtn) ; 


Word 
Pointer 


updateRate; 
userUpdateRtn; 
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NSShutDown  $0319 

Shuts  down  the  Note  Synthesizer  and  turns  off  all  generators.  An  application  should  make 
this  call  before  quitting. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1923        nsNotmit  Note  Synthesizer  not  started  up. 

C  extern  pascal  void  NSShutDown () ; 
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NSVersion     $0419 

Returns  the  version  number  of  the  Note  Synthesizer.  Refer  to  Appendix  A,  "Writing  Your 
Own  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference  for  information  about  the  format  and 
content  of  the  versionNum  return  value. 


Stack  before  call 

Previous  contents 

Space 

Word— Space  for  result 

<— SP 

Stack  after  call 

Previous  contents 

versionNum 

Word— Note  Synthesizer  version  number 

<— SP 

Errors                  None 

C 

exte 

rn  pascal  Word  NSVersion () ; 
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NSReset     $0519 

Resets  the  Note  Synthesizer. 

A  Warning       An  application  must  not  make  this  call,  a 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  NSReset (); 


41-18     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


NSStatus     $0619 

Returns  a  Boolean  value  indicating  whether  the  Note  Synthesizer  is  active.  If  the  Note 
Synthesizer  is  active,  ns  status  returns  TRUE.  Otherwise,  the  call  returns  FALSE. 

♦   Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  NSStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  the  Note  Synthesizer  is  not  active,  the  returned  value  will 
be  FALSE  (NIL). 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


startStatus 


Errors 
C 


None 


Word— Boolean;  TRUE  if  the  Note  Synthesizer  is  started 
<— SP 


extern  pascal  Boolean  NSStatus  (); 
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Note  Synthesizer  calls 

The  following  sections  discuss  the  Note  Synthesizer  tool  calls. 


AllNotesOff    $0D19 


Turns  off  all  Note  Synthesizer  generators  and  sets  their  priorities  to  0.  It  does  not  affect 
generators  not  used  by  the  Note  Synthesizer,  such  as  those  allocated  to  the  freeform 
synthesizer. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  AllNotesOff () ; 
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AllocGen     $0919 

Requests  the  allocation  of  a  sound  generator.  Returns  a  generator  number  from  0  to  13. 
The  call  will  reallocate  a  generator  if  all  generators  are  allocated  and  the  specified 
requestPriority  exceeds  that  of  one  of  the  previously  allocated  generators. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


requestPriority 


Stack  after  call 


Word— Space  for  result 
Word— Desired  generator  priority 
<— SP 


Previous  contents 


genNum 


Errors 


Word— Number  of  allocated  generator 
<— SP 


No  generators  available  to 

allocate. 

Note  Synthesizer  not  started  up. 


$1921    nsNotAvail 

$1923    nsNotlnit 

extern  pascal  Word  AllocGen (requestPriority) ; 

Word      requestPriority; 
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DeAllocGen    $0A19 

Sets  the  named  generator's  allocation  priority  to  zero  and  halts  its  oscillators.  Any 
subsequent  allocation  request  with  a  valid  requestPriority  will  then  succeed. 

Parameters 

Stack  before  call 


Previous  contents 


genNum 


Stack  after  call 


Word— Number  of  generator  to  deallocate 
<— SP 


Previous  contents 


Errors 
C 


<— SP 

$1922        nsBadGenNum  Invalid  generator  number, 

extern  pascal  void  DeAllocGen (genNum) ; 
Word  genNum; 
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NoteOff    $0C19 


Switches  the  specified  generator  to  release  mode,  which  causes  the  note  being  generated 
to  die  out.  When  the  note's  volume  is  0,  the  generator's  priority  is  set  to  0,  and  it  is 
considered  to  be  off.  The  genNum  and  semitone  parameters  should  be  set  to  the  same 
values  specified  in  the  corresponding  NoteOn  call. 


Parameters 

Stack  before  call 

Previous  contents 

genNum 

Word— Generator  number 

semitone 

Word— Note  being  played 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C                             exte 

rn  pascal  void  NoteOff (genNum,    semitone) 

Word 

genNum,    semitone; 
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NoteOn 


$0B19 


Initiates  the  generation  of  a  note  on  a  specified  generator.  The  genNum  parameter  should 
be  a  value  returned  by  the  AiiocGen  call.  The  semitone  parameter  is  a  standard  MIDI 
value  from  0  to  127,  where  middle  C  is  designated  by  the  value  60.  The  volume  parameter 
is  a  value  from  0  to  127  that  can  be  treated  as  synonymous  with  MIDI  velocity.  The  value  is 
copied  into  the  generator  control  block,  and  is  used  to  sale  the  note's  amplitude.  A 
change  of  16  steps  in  this  parameter  specifies  a  change  of  6  decibels  in  amplitude.  The 
instrumentPtr  parameter  is  a  pointer  to  an  instrument.  See  "Instruments"  earlier  in  this 
chapter  for  more  information  on  the  instrument  data  structure. 

♦   Note:  Experiment  with  the  volume  parameter  and  envelope  amplitudes;  if  the  sum  of 
these  two  values  is  too  small,  the  note  being  played  will  be  inaudible  even  if  everything 
else  is  working  correcdy.  The  dynamic  range  of  the  DOC  is  48  decibels. 


Parameters 

Stack  before  call 


Previous  contents 


genNum 


semitone 


volume 


-  instrumentPtr  - 


Word— Generator  number 
Word— Desired  pitch  for  note 
Word— Desired  volume  for  note 

Long— Pointer  to  instrument  to  play  note 

<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1924 


<— SP 
nsGenAlreadyOn 


The  specified  note  is  already 
being  played. 
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C  extern  pascal  void  NoteOn (genNum,  semitone,  volume, 

instrumentPtr)  ; 

Word      genNum,  semitone,  volume; 
Pointer   instrumentPtr; 

Example 

The  following  example  shows  assembly-language  code  that  allocates  a  generator,  passes 
the  correct  parameters  to  NoteOn,  plays  a  note,  and  turns  off  the  note. 

pushword  #0  ; space  for  GenNum 

pushword  #64  ; priority  of  this  note 

AllocGen  ; retrieve  an  allocated  generator 

pla  ;get  the  generator  number 

sta  GenNum  ; store  it 


definition 


pushword  GenNum 
pushword  Semitone 
pushword  #127 
pushlong  #Instrument 

NoteOn 


After  some  time.. 


pushword  GenNum 
pushword  Semitone 
NoteOff 


;push  parameters: generator 

;  note 

; maximum  volume 

;LONG  pointer  to  instrument 


;push  parameters:  generator 

;  note 

;turn  off  the  note 
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NSSetUpdateRate     $0E19 

Sets  the  Note  Synthesizer's  updateRate  parameter,  as  described  in  the  Nsstartup 
section.  The  specified  updateRate  value  becomes  the  new  updateRate,  and  the  old  value  is 
returned. 


Parameters 

Stack  before  call 

Previous  contents 

Space 

Word— Space  for  result 

updateRate 

Word— New  update  rate 

<— SP 

Stack  after  call 

Previous  contents 

oldRate 

Word— Update  rate  before  call 

<— SP 

Errors                  $1923 

nsNotlnit                          Note 

C 

exte 

rn  pascal  Word  NSSetUpdateRa 

Note  Synthesizer  not  started  up. 
SetUpdc 
Word  updateRate; 
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NSSetUserUpdateRtn     $0F19 

Sets  the  user  update  routine  described  in  the  Nsstartup  section.  The  update  routine 
pointer  is  set  to  the  value  passed  in  the  userUpdateRtn  parameter,  and  the  address  of  the 
old  update  routine  is  returned.  If  there  is  no  user  update  routine  when  this  call  is  made,  it 
returns  a  NULL  pointer.  A  NULL  userUpdateRtn  value  disables  the  current  update  routine. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


-  userUpdateRtn  - 


Stack  after  call 


Long— Space  for  result 

Long— Pointer  to  new  update  routine 
<— SP 


Previous  contents 


oldRtn 


Errors 
C 


$1923 


Long— Pointer  to  old  update  routine 
<— SP 
nsNotmit  Note  Synthesizer  not  started  up. 


extern  pascal  VoidProcPtr 

NSSetUserUpdateRtn (userUpdateRtn) ; 

Pointer   userUpdateRtn; 
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Note  Synthesizer  error  codes 

This  section  lists  the  error  codes  that  may  be  returned  by  Note  Synthesizer  calls. 

Value  Name  Definition 

Note  Synthesizer  already  started  up. 

Sound  Tool  Set  not  started  up. 

No  generators  available  to  allocate. 

Invalid  generator  number. 

Note  Synthesizer  not  started  up. 

The  specified  note  is  already  being  played. 

Incompatible  version  of  Sound  Tool  Set. 


$1901 

nsAlreadylnit 

$1902 

nsSndNotlnit 

$1921 

nsNotAvail 

$1922 

nsBadGenNum 

$1923 

nsNotlnit 

$1924 

nsGenAlreadyOn 

$1925 

soundWrongVer 

41-28    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3  Beta  Draft  30  August  1989 


Chapter  42   Print  Manager  Update 


This  chapter  documents  new  features  of  the  Print  Manager.  The  complete 
reference  to  the  Print  Manager  is  in  Volume  1,  Chapter  15  of  the 
Apple  IIGS  Toolbox  Reference. 
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Error  corrections 

This  section  documents  errors  in  the  Toolbox  Reference. 

m   The  diagram  for  the  job  subrecord,  figure  15-10  on  page  15-14  of  the  Toolbox  Reference, 
shows  that  the  f  Fromusr  field  is  a  word.  This  is  incorrect.  The  f  Fromusr  field  is 
actually  a  byte.  Note  that  the  offsets  for  all  fields  following  this  one  are  incorrect,  as  a 
result.  This  error  is  also  reflected  in  the  tool  set  summary  at  the  end  of  the  chapter. 

■   The  description  of  the  Pr  jobDialog  tool  call  states  that  "The  initial  settings 

displayed  in  the  dialog  box  are  taken  from  the  printer  driver . . .."  This  is  incorrect.  The 
sentence  should  begin  "The  initial  settings  displayed  in  the  dialog  box  are  taken  from 
the  print  record . . .." 


Clarifications 

■   The  existing  Toolbox  Reference  documentation  for  the  PrPicFile  tool  call  does  not 
mention  that  your  program  may  pass  a  NIL  value  for  statusRecPtr.  Passing  a  NIL  pointer 
causes  the  system  to  allocate  and  manage  the  status  record  internally. 

The  PrPixeiMap  call  (documented  in  Volume  1  of  the  Toolbox  Reference)  provides  an 
easy  way  to  print  a  bitmap.  It  does  much  of  the  required  processing,  and  an 
application  need  not  make  the  calls  normally  required  to  start  and  end  the  print  loop. 
The  srcLocPtr  parameter  must  be  a  pointer  to  a  loclnfo  record  (see  Figure  16-3  in 
Chapter  16,  "QuickDraw  II,"  in  the  Toolbox  Reference  for  the  layout  of  the  loclnfo 
record). 
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New  features  in  the  Print  Manager 


The  following  functions  have  been  added  to  the  Print  Manager: 

■  The  port  driver  auxiliary  file  type  of  an  AppleTalk  driver  is  $0003.  Its  file  type  remains 
$BB. 

■  The  PRINTER.SETUP  file  now  saves  separate  settings  for  direct  and  network 
connections  to  printers.  Old  versions  of  the  PRINTER.SETUP  file  are  incompatible 
with  these  changes,  so  the  Print  Manager  will  delete  such  files  and  create  a  new  one  in 
the  correct  format.  Old  settings  are  discarded,  and  the  default  settings  are  used  to 
create  the  new  setup  file. 

■  If  the  Print  Manager  attempts  to  load  a  driver  and  finds  that  it  is  missing,  it  will  pass 
control  to  a  routine  that  determines  what  call  was  being  made  to  the  driver,  pops  the 
parameters  off  the  stack,  and  returns  a  missingDriver  error  ($1301).  It  will  also 
display  an  alert  asking  the  user  to  make  sure  a  printer  and  port  driver  are  selected,  if 
Pr  jobDialog  and  PrStiDialog  are  called. 

■  The  PMStartup  call  does  not  load  any  drivers  into  memory.  Drivers  are  loaded  only 
when  they  are  needed.  The  Print  Manager  does  not  require  that  the  DRIVERS  folder  be 
present,  and  if  it  is  present,  does  not  require  that  there  be  any  drivers  in  it. 

■  The  PrChoosePrinter  call  is  no  longer  supported.  Users  should  now  use  the  Control 
Panel  desk  accessory  to  choose  new  printers.  When  an  application  issues  the 
PrChoosePrinter  call,  the  Print  Manager  will  display  an  alert  directing  the  user  to 
use  the  Control  Panel.  New  applications  should  never  issue  this  call  and  should  not 
include  the  Choose  Printer  item  in  the  file  menu.  Note  that  PMStartup  will  still  load 
the  List  Manager  if  it  has  not  already  been  loaded. 

■  Print  Manager  now  allows  you  to  assign  a  name  to  a  document.  This  feature  is  primarily 
applicable  to  documents  destined  for  AppleTalk  printers. 

■  Currently,  if  a  user  wants  to  print  multiple  copies  of  a  document  in  draft  mode  to  an 
Image  Writer®,  Image  Writer  LQ,  or  Epson  printer,  your  application  must  run  through 
its  print  loop  once  for  each  copy.  The  draft  mode  flag  and  copy  count  fields  are 
located  in  the  Job  subrecord  of  the  print  record. 

■  The  LaserWriter  driver  will  now  use  some  PostScript®  fonts  that  have  been 
downloaded  into  the  printer  by  another  computer. 
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New  Print  Manager  calls 

The  following  sections  discuss  new  Print  Manager  tool  calls. 


PMLoadDriver     $3513 

Loads  the  current  printer  driver,  port  driver,  or  both,  depending  on  the  input  parameter. 
The  current  driver  is  determined  by  the  settings  saved  in  the  PRINTER.SETUP  file. 


Parameters 

Stack  before  call 

Previous  contents 

whichDriver 

Word— Printer  driver  to  load 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Em 

ars                 $1309 

badParam                      The  specified  parameter  is 

invalid. 

C  extern  pascal  void  PMLoadDriver (whichDriver) ; 

Word      whichDriver; 

whichDriver         Specifies  which  printer  driver  to  load.  Legal  values  for  the  driver 
parameter  include 

0  Load  both  drivers. 

1  Load  printer  driver. 

2  Load  port  driver. 
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PMUnloadDriver     $3413 

Unloads  the  current  port  driver,  printer  driver,  or  both,  depending  on  the  input  parameter. 

Parameters 

Stack  before  call 


Previous  contents 

whichDriver 

Word— Printer  driver  to  unload 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Em 

ms                 $1309 

badParam                      The  specified  parameter  is 

invalid. 

C  extern  pascal  void  PMUnloadDriver (whichDriver) ; 

Word  whichDriver; 

whichDriver         Specifies  which  printer  driver  to  unload.  Legal  values  for  the  driver 
parameter  include 

0  Unload  both  drivers. 

1  Unload  printer  driver. 

2  Unload  port  driver. 
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PrGetDocName     $3613 

Returns  a  pointer  to  the  current  document  name  string  for  your  document.  Use  the 
PrSetDocName  tool  call  to  set  or  change  the  document  name. 

Note  that  there  is  only  one  active  document  name  for  the  system  at  any  given  time.  Your 
application  must  correctly  manage  this  name  in  the  context  of  the  document  being 
printed. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


-    docNamePtr 


Errors 
C 


None 


Long— Pointer  to  document  name  string  (Pascal  string) 
<— SP 


extern  pascal  Pointer  PrGetDocName () ; 
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PrGetPgOrientation     $3813 

Returns  a  value  indicating  the  current  page  orientation  for  the  specified  document. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


-  prRecordHandle  - 


Stack  after  call 


Word— Space  for  result 

Long— Handle  to  print  record  for  document 

<— SP 


Previous  contents 


orientation 


Errors 
C 


None 


Word— Page  orientation:  0=portrait,  1  landscape 
<— SP 


extern  pascal  Word 

PrGetPgOrientation (prRecordHandle) 

Handle    prRecordHandle; 
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PrGetPrinterSpecs     $1813 

Returns  information  about  the  currently  selected  printer. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Space 


Word— Space  for  result 
Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


characteristics 


printerType 


Word— Word  defining  printer  characteristics 
Word— Word  indicating  the  type  of  printer  connected 
<— SP 


Errors 


None 


C  extern  pascal  PrinterSpecs  PrGetPgOrientation () ; 

characteristics       Defines  the  features  of  the  particular  printer: 

Reserved  bits  2-15     Must  be  set  to  0 

color  bits  0-1       Indicates  color  capability: 

00  -  Can't  determine 

01  -  Black  and  white  only 
10 -Color 

11 -Invalid  value 

printerType  Indicates  the  type  of  printer  selected: 

0  undefined 

1  Image  Writer  I  or  II 

2  Image  Writer  LQ 

3  LaserWriter®  family  (LaserWriter,  Plus,  and  II) 

4  Epson 
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PrSetDocName     $3713 

Sets  the  document  name  for  use  with  AppleTalk  printers.  Print  Manager  passes  this  name 
when  connecting  to  printers  and  spoolers,  so  that  the  destination  printer  may  properly 
report  the  name. 

Note  that  there  is  only  one  active  document  name  for  the  system  at  any  given  time.  Your 
application  must  correctly  manage  this  name  in  the  context  of  the  document  being 
printed. 

In  some  status  windows,  the  document  name  may  be  truncated.  To  avoid  name 
truncation,  you  should  use  names  containing  fewer  than  32  characters. 

Parameters 

Stack  before  call 


Previous  contents 


-    docNamePtr    - 


Stack  after  call 


Long— Pointer  to  document  name  string  (Pascal  string) 
<— SP 


Previous  contents 


Errors 


None 


<— SP 


extern  pascal  void  PrSetDocName (docNamePtr) ; 
Pointer   docNamePtr; 
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Previously  undocumented  Print  Manager  calls 

The  following  calls  have  not  previously  been  documented,  but  may  be  useful  to 
application  programmers. 


PrGetNetworkName         $2B13 

Returns  the  AppleTalk  network  name  for  the  currently  selected  printer.  If  the  user  has 
selected  a  non-networked  printer,  the  call  returns  a  ML  pointer. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Long— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


-     netNamePtr    - 


Errors 
C 


Long— Pointer  to  printer  network  name  string  (Pascal  string) 
<— SP 

None 

extern  pascal  Pointer  PrGetNetworkName () ; 
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PrGetPortDvrName     $2913 

Returns  the  name  string  for  the  currently  selected  port  driver. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Long — Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


-  prtDvrNamePtr 


Long— Pointer  to  port  driver  name  string  (Pascal  string) 
<— SP 


Errors 
C 


None 


extern  pascal  Pointer  PrGetPortDvrName () ; 
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PrGetPrinterDvrName     $2813 

Returns  the  name  string  for  the  currently  selected  printer  driver. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


prtDvrNamePtr 


Errors 
C 


None 


Long— Pointer  to  printer  driver  name  string  (Pascal  string) 
<— SP 


extern  pascal  Pointer  PrGetPrinterDvrName () ; 
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PrGetUserName     $2A13 

Returns  the  user  name  as  entered  in  the  Control  Panel. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


-    userNamePtr 


Errors 
C 


None 


Long— Pointer  to  user  name  string  (Pascal  string) 
<— SP 


extern  pascal  Pointer  PrGetUserName () ; 
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PrGetZoneName     $2513 

Returns  the  name  string  for  the  currently  selected  AppleTalk  print  zone.  If  the  user  has 
selected  a  non-networked  printer,  then  the  call  returns  a  NIL  pointer. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


-   zoneNamePtr  - 


Errors 
C 


Long— Pointer  to  zone  name  string  (Pascal  string) 
<— SP 

None 

extern  pascal  Pointer  PrGetZoneName () ; 
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Print  Manager  error  codes 


This  section  lists  all  valid  Print  Manager  error  codes. 


Value 


$1301 
$1302 

$1303 
$1306 

$1307 
$1308 
$1309 
$130A 

$1321 


Name 


Definition 


Specified  driver  not  in  the  DRIVERS 
subdirectory  of  the  SYSTEM  subdirectory. 
Specified  port  not  selected  in  the  control 
panel. 

No  print  record  specified 
Connection  cannot  be  established  with  the 
LaserWriter. 

Read-write  error  on  the  LaserWriter. 
Cannot  establish  connection  with  Image  Writer. 
Invalid  parameter  for  load  or  unload. 
caiiNotSupported    Tool  call  is  not  supported  by  current  version  of 

the  driver. 

startUpAlreadyMade 

LLDStartup  call  already  made. 


mi  ssingD river 

portNotOn 

noPrintRecord 
papConnNotOpen 

papReadWriteErr 

pntrConFailed 

badParam 
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Chapter  43   QuickDraw  n  Update 


This  chapter  documents  new  features  of  QuickDraw™  II.  The  complete 
reference  to  QuickDraw  II  is  in  Volume  2,  Chapter  16  of  the 
Apple  IIGS  Toolbox  Reference. 
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Error  corrections 


The  following  items  provide  corrections  to  the  documentation  for  QuickDraw  II  in  the 
Apple  IIGS  Toolbox  Reference: 

■  The  documentation  in  the  Toolbox  Reference  that  explains  pen  modes  is  somewhat 
misleading.  There  are,  in  fact,  8  drawing  modes,  and  you  may  set  the  pen  to  draw  lines 
and  other  elements  of  graphics  in  any  of  these  modes.  There  are  also  16  modes  used  for 
drawing  text,  and  they  are  completely  independent  of  the  graphic  pen  modes.  The  8 
drawing  modes  listed  in  Table  16-9  on  page  16-235  are  valid  modes  for  either  the  text 
pen  or  the  graphics  pen.  You  can  set  either  pen  to  any  of  these  modes  by  using  the 
appropriate  calls.  You  can  also  set  the  text  pen  to  8  other  modes.  These  modes  are 
listed  in  the  table  on  page  16-260  of  the  Toolbox  Reference.  The  setPenMode  call  sets 
the  mode  used  by  the  graphics  pen;  the  SetTextMode  call  sets  the  mode  used  by  the 
text  pen.  Setting  either  one  does  not  affect  the  other. 

■  There  are  two  versions  of  the  Apple  IIGS  standard  640-mode  color  tables,  one  on  page 
16-36  and  one  on  page  16-159.  The  two  tables  are  different;  Table  16-7  on  page  16-159 
is  correct. 

■  In  the  QuickDraw  II  chapter,  the  Apple  IIGS  Toolbox  Reference  states  that  the 
coordinates  passed  to  the  LineTo  andMoveTo  calls  should  be  expressed  as  global 
coordinates.  In  fact,  the  coordinates  must  be  local  coordinates,  and  must  refer  to  the 
GrafPort  in  which  the  drawing  or  moving  takes  place. 
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New  features  in  QuickDraw  n 

The  following  information  describes  new  features  in  this  version  of  QuickDraw  II. 

■  QuickDraw  II  now  supports  16  bit  by  8  bit  pixel  patterns  in  640  mode.  To  use  these 
larger  patterns,  set  the  high-order  bit  (bit  15)  of  the  arcRot  word  in  the  GrafPort 
record  to  1.  QuickDraw  n  will  then  use  all  32  bytes  of  the  passed  pattern.  Since  the 
openPort  and  initPort  tool  calls  clear  this  bit,  existing  applications  will  work  fine. 

PointinRect  now  works  as  previously  documented. 

■  In  the  FONT  folder  on  your  system  disk  you  will  find  a  file  named  FASTFONT.  This  file 
contains  a  special  version  of  the  Shaston  8  font  that  will  provide  markedly  improved 
performance  for  text  drawing  under  many  circumstances.  Specifically,  this  font  can  be 
used  whenever  you  are  drawing  plain,  black  text  on  a  white  background  into  a 
rectangularly  clipped  region.  While  this  may  sound  overly  restrictive,  most  applications 
draw  text  in  precisely  this  way.  This  font  reduces  text  drawing  time  by  more  than  half. 

To  use  this  font,  QuickDraw  n  must  find  it  in  your  FONT  folder  when  the  tool  is 
started.  If  your  application  draws  text  to  an  off-screen  bitmap,  use  OpenPort  and 
initPort  to  set  up  the  off-screen  buffers  in  order  to  insure  that  FASTFONT  is 
properly  installed. 


QuickDraw  n  speed  enhancement 

In  addition  to  FASTFONT,  QuickDraw  II  has  several  other  changes  that  improve  drawing 
performance.  First,  pattern  filling  in  modecopy  and  modexoR  now  operates  between  2 
and  4  times  faster.  The  remaining  changes  require  that  you  modify  your  application  to 
take  advantage  of  the  performance  improvements  they  offer. 

QuickDraw  II  now  supports  hardware  shadowing  of  screen  images.  This  feature  uses  32  KB 
of  bank  1  memory  to  store  the  screen  image.  By  storing  the  image  in  memory,  QuickDraw 
II  can  offer  an  8  to  20  percent  speed  improvement  in  all  operations.  You  control  whether 
QuickDraw  II  uses  the  shadow  memory  by  setting  a  flag  in  the  masterSCB  parameter 
passed  to  the  oostartup  tool  call.  If  QuickDraw  II  cannot  allocate  the  needed  memory, 
it  will  reset  the  flag  and  operate  without  shadowing  in  effect.  Use  the  GetMasterSCB 
tool  call  to  read  the  masterSCB  back  and  check  shadow  status. 


Chapter  43    QuickDraw  II  Update      43-3 


Apple  11GS  Toolbox  Reference,  Volumes 


Beta  Draft 


30  August  1989 


In  addition,  your  application  can  further  improve  QuickDraw  II  performance  by  following 
some  simple  rules.  First,  your  application  must  only  change  GrafPort  fields  via  QuickDraw 
II  tool  calls,  not  by  directly  accessing  the  record  fields.  Next,  for  best  results  perform 
similar  operations  in  groups.  For  example,  if  your  application  needs  to  erase  and  redraw 
four  rectangles,  it  should  do  all  the  erases  together,  then  all  the  draws.  In  this  manner, 
QuickDraw  II  only  has  to  change  its  drawing  pattern  twice,  rather  than  eight  times.  Your 
application  tells  QuickDraw  II  that  it  will  follow  these  fast  port  rules  by  setting  a  bit  in  the 
masterSCB  passed  to  QDStartup. 

The  masterSCB  now  has  the  following  format: 


fUseShadowing 

bit  15 

Controls  use  of  hardware  shadowing  by  QuickDraw 

II: 

0  -  No  shadowing 

1  -  Shadowing 

fFastPortAware 

bit  14 

Indicates  whether  application  follows  fast  port  rules 

0  -  Does  not  use  fast  port  rules 

1  -  Does  use  fast  port  rules 

Reserved 

bits  8-13 

Must  be  set  to  0 

SCB 

bits  0-7 

Use  standard  SCB  values 
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New  font  header  layout 

The  font  header  has  been  expanded  to  include  a  new  field  containing  additional 
addressing  information.  Figure  43-1  shows  the  new  layout  for  the  font  header.  For 
information  about  the  old  fields,  see  Chapter  16,  "QuickDraw  n,"  in  Volume  2  of  the 
Toolbox  Reference. 


Figure  43-1  New  font  header  layout 


$00 

-     offsetToMF 

- 

$02 

—       family 

- 

$04 

—       style 

- 

$06 

—       size 

- 

$08 

—      version 

- 

$0A 

—     fbrExtent 

- 

$0C 

—    hlghowTLoc 

- 

$0E 

i 

Wrod— Offset  in  words  to  Macintosh  font  part 

Word— Font  family  number 

Word— Style  font  was  designed  with 

Word— Point  size 

Word— Version  number  of  the  font  definition 

Word— Font  bounds  rectangle  extent 

Word— High-order  word  of  address  to  offset/width  table 

Bytes— Additional  fields,  if  any 


highowTLoc        Defines  the  high-order  word  of  the  address  to  the  offset/width  table 
for  the  font.  The  owtloc  field  contains  the  low-order  word  of  the 
address.  Together,  these  two  fields  form  a  full  32-bit  address. 


Chapter  43    QuickDraw  II  Update      43-5 


Apple  I1GS  Toolbox  Reference,  Volume  3  Beta  Draft  30  August  1989 


Chapter  44   QuickDraw  n  Auxiliary  Update 


This  chapter  documents  new  features  in  QuickDraw  II  Auxiliary.  The 
complete  reference  to  QuickDraw  II  Auxiliary  is  in  Volume  2,  Chapter  17 
of  the  Apple  IIGS  Toolbox  Reference. 
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New  features  in  QuickDraw  n  Auxiliary 

■   QuickDraw  II  now  supports  text  justification  within  pictures.  Note  that  QuickDraw  II 
justifies  the  text  only  when  drawing  the  picture,  not  in  the  stored  picture  image.  You 
control  text  justification  in  pictures  by  setting  a  bit  flag  in  the  f  ontFiags  word  of 
the  GrafPort  record.  Use  the  setFontFiags  tool  call  to  change  the  state  of  this  bit. 

The  f  ontFiags  word  is  defined  as  follows: 

Reserved  bits  4-15  Must  be  set  to  0 

f  Text  Just        bit  3  Controls  text  justification  in  pictures: 

0  -  No  text  justification 

1  -  Justify  text 

bits  0-2  Use  standard  f  ontFiags  values  (see  page  16- 

56  in  the  Toolbox  Reference  for  a  description  of 
these  bits) 
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New  QuickDraw  n  Auxiliary  calls 

Two  new  QuickDraw  II  tool  calls,  caicMask  and  seedFiii,  provide  enhanced 
functionality  to  the  application  programmer  who  wants  to  create  graphics  entry  or  editing 
software.  A  third  new  call,  SpeciaiRect,  provides  a  high-performance  rectangle  frame 
and  fill  operation. 


CaicMask    $0E12 

Generates  a  mask  from  a  specified  source  image  and  pattern,  by  filling  inward  from  the 
bounding  rectangle.  The  shape  of  the  resulting  mask  consists  of  all  areas  in  the  source 
image  where  leaking  does  not  occur  (all  enclosed  areas  within  the  rectangle): 


Source  rect 


Source  image 


Computed 

CaicMask  shape 


This  call  differs  from  SeedFiii  only  in  that  it  works  from  the  "outside  in",  whereas 
SeedFiii  goes  "inside  out",  filling  all  enclosed  areas  starting  from  a  specified  interior 
point  (see  "seedFiii"  in  this  chapter  for  details). 
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caicMask  is  most  commonly  used  to  implement  a  lasso  tool,  by  having  caicMask 
determine  the  selected  shape  by  filling  inward  from  the  lasso  rectangle: 


Source  image         Computed  Write  pattern 

CaicMask  shape   was-l,this 

indicates  all  l's 


Destination  image 
containing  anything 
(it  will  be  preinitialized) 


Destination  is 

now  a  l's  active  mask 


For  this  use,  set  the  call  parameters  as  follows: 

destMode  portion  of  resMode    %0010  (clear  destination  to  zeroes  before  drawing) 

patternPtr  $FFFFFFFF  (use  all  ones  pattern  when  drawing  to 

destination) 

This  call  does  not  perform  automatic  scaling;  therefore,  the  source  and  destination 
rectangles  must  be  of  equal  size.  In  addition,  note  that  the  fill  is  not  clipped  to  the  current 
port,  and  that  the  resulting  image  cannot  be  stored  into  a  QuickDraw  II  picture. 

A  Important      Your  application  must  word-align  both  the  source  and  destination 
rectangles  in  order  to  assure  an  accurate  fill,  a 
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Par 

Stac 

ameters 

k  before  call 

Previous  contents 

Long— Pointer  to 
Long— Pointer  to 
Long— Pointer  to 

Long— Pointer  to 
Word— Resolutio 
Long— Pointer  to 

Long— Pointer  to 
<— SP 

<— SP 

memErr 
badRectSize 

destModeError 

-   srcLodnfoPtr   - 

source  locinf  o  data  record 

srcRect 

source  rectangle  data  record 

-  destLodnfoPtr  - 

destination  locinf  o  data  record 

destRect 

destination  rectangle  data  record 

resMode 

ti  mode 

-     patternPtr 

fill  pattern 

-      leakTblPtr      - 

leak-through  color  table 

Stac 

k  after  call 
Previous  contents 

- 

Em 

ars                  $0201 
$1211 

$1212 

NewHandle  error  occurred 

1)  Height  or  width  is  negative, 

2)  destRect  not  same  size  as 
srcRect,  or  3)  source  or 
destination  rectangle  not  within 
its  boundary  rectangle 
destMode  portion  of  resMode 
invalid 

extern  pascal  void  CalcMask  (srcLodnfoPtr,  srcRect, 
destLodnfoPtr,  destRect,  resMode, 
patternPtr,  leakTblPtr) ; 

Pointer    srcLodnfoPtr,  srcRect,  destLodnfoPtr, 

destRect,  patternPtr,  leakTblPtr; 
Word      resMode; 
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srcLocInfoPtr         Points  toaiocinfo  data  record  containing  the  definition  for  the 
source  rectangle  for  the  fill  operation. 

srcRect  Points  to  a  rectangle,  in  local  coordinates,  that  contains  the  source 

pixel  image. 

destLodnfoPtr,  destRect 

Refer  to  output  locinf  o  record  and  rectangle,  respectively.  These 
fields  allow  you  to  copy  the  output  to  a  different  location  in  a 
different  rectangle.  If  you  want  the  output  of  the  operation  to  overlay 
the  input  image,  set  the  source  and  destination  pointers  to  the  same 
values. 


resMode 


destMode 


Reserved 


res 


Indicates  the  resolution  mode  for  the  fill  as  well  as  initialization  and 
drawing  options: 

bits  12-15    Indicates  initialization  and  drawing  options: 

0000  -  copy  source  to  destination  (obliterating 
destination) 

0001  -  leave  destination  alone  (overlay  source  onto 
destination) 

0010  -  initialize  destination  to  zeroes  before  drawing 

0011  -  initialize  destination  to  ones  before  drawing 
other  values  are  invalid 


bits  2-11     Must  be  set  to  0 

bits  0-1       Indicates  the  resolution  for  the  operation: 
00 -640  pure 
01  -  640  dithered 
10  -  320  mode 
11 -invalid 

patternPtr  Pointer  to  the  fill  pattern  for  the  operation,  or  flag  specifying  special 

fill  pattern: 

NIL  Use  an  all  zeroes  pattern  when  writing  to  destination 

$FFFFFFFP  Use  an  all  ones  pattern  when  writing  to  destination 

Other  Assumed  to  be  valid  pointer  to  fill  pattern 


44-6      Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  11CS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


leakTblPtr  Pointer  to  a  structure  that  defines  the  colors  to  be  covered.  The 

structure  contains  a  count  word,  indicating  the  number  of  color 
entries  in  the  table,  and  a  color  entry  for  each  color  to  be  leaked.  Each 
color  entry  contains  the  offset  into  the  color  table  for  that  color. 


$00 
$02 


count  -  Word— Count  of  color  entries  to  follow 

coiorEnt  ries        :  count  Words— Offset  into  color  table  for  each  color 
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SeedFill     $0D12 

Generates  a  mask  from  a  specified  source  image  and  pattern,  by  filling  outward  from  a 
starting  point  within  the  source  image.  The  shape  of  the  resulting  mask  consists  of  the 
enclosed  area  in  the  source  image  surrounding  the  starting  (or  seed)  point: 


Source  rect 


Seed  point 


Source  image 


Computed 

SeedFill shape 


This  call  differs  from  caicMask  only  in  that  it  works  from  the  "inside  out",  whereas 
CaicMask  goes  "outside  in"  (see  "caicMask"  in  this  chapter  for  details). 
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seedFiii  is  a  versatile  tool.  Most  simply,  you  can  use  it  to  implement  a  paint  bucket 
tool: 


Source  image        Computed  Write  pattern 

SeedFill shape 


Original  source  Source  image 

image  (passed  with  pattern  added 

again  as  destination) 


For  this  operation,  use  the  following  call  parameter  values: 

destMode  portion  of  resMode    %0001  (do  not  change  destination  image  before 


patternPtr 


drawing) 

Pointer  to  fill  color  or  pattern 


Chapter  44    QuickDraw  II  Auxiliary  Update      44-9 


Apple  11GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


In  order  to  add  an  undo  capability  to  the  paint  bucket,  specify  a  different  destination: 


>  2^ 


Source  image         Computed  Write  pattern 

SeedFill shape 


Destination  image 
containing  anything 
(it  will  be  completely 
overwritten) 


Destination  now 
contains  filled 
copy  of  source 
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As  a  more  complex  example,  consider  this  "from  the  inside"  lasso  tool: 


Source  image       Computed  Write  pattern        Destination  image  Destination  is  now 

SeedFiii  shape     was-l,this  containing  anything         a  l's  active  mask 

indicates  all  l's      (it  will  be  preinitial ized) 


For  this  operation,  use  the  following  call  parameter  values: 

destMode  portion  of  resMode    %0010  (clear  destination  to  zeroes  before  drawing) 
patternPtr  $FFFFFFFF  (use  all  ones  pattern  when  drawing  to 

destination) 

This  call  does  not  perform  automatic  scaling;  therefore,  the  source  and  destination 
rectangles  must  be  of  equal  size.  In  addition,  note  that  the  fill  is  not  clipped  to  the  current 
port,  and  that  the  resulting  image  cannot  be  stored  into  a  QuickDraw  II  picture. 


A  Important      Your  application  must  word-align  both  the  source  and  destination 
rectangles  in  order  to  assure  an  accurate  fill,  a 
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Parameters 

Stack  before  call 


Previous  contents 


-   srcLodnfoPtr 


srcRect 


-  destLodnfoPtr  - 


destRect 


seedH 


seedV 


resMode 


patternPtr 


-      leakTblPtr      - 


Stack  after  call 


Long— Pointer  to  source  locinf  o  data  record 
Long— Pointer  to  source  rectangle  data  record 
Long— Pointer  to  destination  locinf  o  data  record 
Long— Pointer  to  destination  rectangle  data  record 

Word— Horizontal  offset  (pixel)  to  starting  fill  point 
Word— Vertical  offset  (pixel)  to  starting  fill  point 
Word— Resolution  mode 

Long— Pointer  to  fill  pattern 

Long— Pointer  to  leak-through  color  table 

<— SP 


Previous  contents 


Errors 


<— SP 


$0201 

memErr 

NewHandle  error  occurred 

$1211 

badRectSize 

1)  Height  or  width  is  negative, 

2)  destRect  not  same  size  as 
srcRect,  or  3)  source  or 
destination  rectangle  not  within 
its  boundary  rectangle 

$1212 

destModeError 

destMode  portion  of  resMode 
invalid 
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extern  pascal  void  SeedFill (srcLocInfoPtr,  srcRect, 
destLodnfoPtr,  destRect,  seedH,  seedV, 
resMode,  patternPtr,  leakTblPtr) ; 


Pointer 


Word 


srcLocInfoPtr,  srcRect,  destLodnfoPtr, 
destRect,  patternPtr,  leakTblPtr; 
seedH,  seedV,  resMode; 


srcLocInfoPtr        Points  toaiocinfo  data  record  containing  the  definition  for  the 
source  rectangle  for  the  fill  operation. 

srcRect  Points  to  a  rectangle,  in  local  coordinates,  that  contains  the  source 

pixel  image. 

destLodnfoPtr,  destRect 

Refer  to  output  locinf  o  record  and  rectangle,  respectively.  These 
fields  allow  you  to  copy  the  output  to  a  different  location  in  a 
different  rectangle.  If  you  want  the  output  of  the  operation  to  overlay 
the  input  image,  set  the  source  and  destination  pointers  to  the  same 
values. 


seedH,  seedV 


resMode 


destMode 


Reserved 


res 


Specify  the  horizontal  and  vertical  offsets  into  the  source  pixel  image 
of  the  point  at  which  to  start  the  fill  operation. 

Indicates  the  resolution  mode  for  the  fill  as  well  as  initialization  and 
drawing  options: 

bits  12-15   Indicates  initialization  and  drawing  options: 

0000  -  copy  source  to  destination  (obliterating 
destination) 

0001  -  leave  destination  alone  (overlay  source  onto 
destination) 

0010  -  initialize  destination  to  zeroes  before  drawing 

0011  -  initialize  destination  to  ones  before  drawing 
other  values  are  invalid 

bits  2-11     Must  be  set  to  0 

bits  0-1       Indicates  the  resolution  for  the  operation: 
00 -640  pure 
01  -  640  dithered 
10  -  320  mode 
11 -invalid 


Chapter  44    QuickDraw  II  Auxiliary  Update     44-13 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


patternPtr  Pointer  to  the  fill  pattern  for  the  operation,  or  flag  specifying  special 

fill  pattern: 

Use  an  all  zeroes  pattern  when  writing  to  destination 
Use  an  all  ones  pattern  when  writing  to  destination 
Assumed  to  be  valid  pointer  to  fill  pattern 

leakTblPtr  Pointer  to  a  structure  that  defines  the  colors  to  be  covered.  The 

structure  contains  a  count  word,  indicating  the  number  of  color 
entries  in  the  table,  and  a  color  entry  for  each  color  to  be  leaked.  Each 
color  entry  contains  the  offset  into  the  color  table  for  that  color: 


$00 
.$02 


count  -  Word— Count  of  color  entries  to  follow 


coiorEntries        :  count  Words— Offset  into  color  table  for  each  color 
_J 
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SpecialRect     $002 

Frames  and  fills  a  rectangle  in  a  single  call,  making  separate  calls  to  FrameRect  and 
FiliRect  unnecessary. 

The  pen  used  to  draw  the  rectangle  frame  in  640  mode  is  2  pixels  wide  and  1  pixel  high;  in 
320  mode,  the  pen  is  1  pixel  wide  and  1  pixel  high. 


Parameters 

Stack  before  call 

Previous  contents 

recPtr 

Long — Pointer  to  rectangle  to  draw 

frameColor 

Word— Color  of  rectangle  frame 

fillColor 

Word— Color  of  rectangle  interior 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C 

exte 

rn  pascal  void  SpecialRect (recP1 

fillColor) ; 

Pointer   recPtr; 

Word      frameColor,  fillColor; 


frameColor,  fillColor 

The  low-order  four  bits  of  each  of  these  parameters  specify  the  color. 


Chapter  44    QuickDraw  II  Auxiliary  Update     4415 


Apple  IIGS  Toolbox  Reference,  Volume  3  Beta  Draft  30  August  1989 


Chapter  45   Resource  Manager 


This  chapter  documents  the  features  of  the  new  Resource  Manager.  This 
is  a  new  tool  set,  not  previously  documented  in  the 
Apple  IIGS  Toolbox  Reference. 
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About  the  Resource  Manager 

The  Resource  Manager  provides  applications  access  to  resources,  which  can  contain  such 
items  as  menus,  fonts,  and  icons.  Most  basically,  a  resource  is  a  formatted  collection  of 
data.  The  Resource  Manager  does  not  know  the  format  or  content  of  any  given  resource. 
Your  application  defines  the  content  of  its  resources,  or  may  use  standard  resources 
defined  by  the  system.  Resource  Manager  facilities  allow  applications  to  create,  use,  and 
manipulate  these  resources. 

Generally,  your  program  will  access  the  Resource  Manager  indirectly,  as  a  result  of  using 
other  tool  sets,  such  as  the  Window  Manager  or  Control  Manager,  which  use  resources. 
However,  if  your  program  manages  its  own  resources,  it  will  have  to  issue  some  Resource 
Manager  calls  direcdy.  Further,  you  may  want  to  write  a  program  that  creates  and  edits 
resources.  Such  a  program  would  make  thorough  use  of  Resource  Manager  tool  calls. 

The  following  table  summarizes  the  capabilities  of  the  Resource  Manager  in  a  grouped 
listing  of  its  tool  calls.  Later  sections  of  this  chapter  discuss  resources  in  greater  detail, 
and  define  the  precise  syntax  for  the  Resource  Manager  tool  calls. 


Routine 


Description 


Housekeeping  routines 

ResourceBootlnit 

ResourceStartUp 

ResourceShutDown 

ResourceReset 

ResourceVersion 
ResourceStatus 


Called  only  by  the  Tool  Locator— must  not  be  called  by 

an  application 

Informs  the  Resource  Manager  that  an  application 

wants  to  use  its  facilities 

Informs  the  Resource  Manager  that  an  application  is 

finished  using  resource  tool  calls 

Called  only  when  the  system  is  reset— must  not  be  called 

by  an  application 

Returns  the  Resource  Manager  version  number 

Returns  the  Resource  Manager's  operational  status 
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Resource  access  routines 

AddResource 

RemoveResource 
LoadResource 
LoadAbsResource 
GetlndResource 

ReleaseResource 
DetachResource 


WriteResource 

Resource  maintenance  routines 


Creates  a  new  resource  and  adds  it  to  a  specified 

resource  file 

Deletes  a  resource  from  a  resource  file 

Loads  a  resource  into  memory 

Loads  a  resource  into  a  specified  memory  location 

Loads  a  resource  given  an  index  into  a  specified 

resource  type 

Removes  a  loaded  resource  from  memory 

Removes  a  loaded  resource  from  the  control  of  the 

Resource  Manager,  but  leaves  the  resource  in  memory 

Writes  a  changed  resource  to  its  resource  file 


GetResourceAttr 

SetResourceAttr 

GetResourceSize 

MarkResourceChange 

SetResourcelD 

UniqueResourcelD 

CountTypes 

GetlndTypes 

CountResources 
MatchResourceHandle 
ResourceConverter 
SetResourceLoad 


Returns  the  attributes  of  a  resource 

Sets  the  attributes  of  a  resource 

Returns  the  size  in  bytes  of  a  resource 

Sets  the  value  of  the  changed  attribute  of  a  resource 

Changes  the  ID  of  a  resource 

Obtains  a  unique  resource  ID  for  a  resource  of  a 
specified  type 

Returns  the  number  of  different  resource  types  in  all 

open  resource  files  for  an  application 

Returns  a  resource  type  value  associated  with  an  index 

into  the  array  of  all  active  resource  types 

Returns  the  number  of  resources  of  a  specified  type 

Finds  the  ID  and  type  of  a  resource,  given  its  handle 

Installs  resource  converter  routines 

Controls  whether  the  Resource  Manager  loads  resources 

from  disk 
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Resource  file  routines 


CreateResourceFile 
OpenResourceFile 

CloseResourceFile 
UpdateResourceFile 


GetCurResourceFile 
SetCurResourceFile 
SetResourceFileDepth 

GetOpenFileRefNum 

HomeResourceFile 

GetMapHandle 


Creates  and  initializes  a  resource  file 

Opens  a  resource  file  for  access  by  the  Resource 

Manager 

Closes  an  open  resource  file 

Writes  all  in-memory  resource  changes  to  the 

appropriate  resource  file,  making  those  changes 

permanent 

Returns  the  file  ID  of  the  current  resource  file 

Sets  the  current  resource  file 

Sets  the  number  of  resource  files  that  the  Resource 

Manager  will  search  when  locating  a  specific  resource 

Returns  the  GS/OS  file  reference  number  for  an  open 

resource  file 

Returns  the  file  ID  of  the  resource  file  that  contains  a 

specified  resource 

Returns  the  handle  of  a  resource  map  for  an  open 

resource  file 


Application  switching  routines 


GetCurResourceApp 


SetCurResourceApp 


Returns  the  User  ID  of  the  application  currently  using 
the  Resource  Manager 

Sets  the  User  ID  of  the  application  now  using  the 
Resource  Manager 
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About  resources 

A  resource  is  a  formatted  collection  of  data,  such  as  a  menu,  a  font,  or  a  program  itself. 
The  format  of  the  data  in  a  resource  is  determined  by  the  program  that  uses  the  resource, 
or  by  the  system  for  standard  resources.  A  program  maintains  its  resources  separate  from 
the  program  code  itself.  This  very  separation  is  the  primary  benefit  of  using  resources- 
program  code  is  immune  to  data  content  changes,  and  program  data  is  immune  to 
program  code  changes,  even  to  changes  in  programming  language. 

Resources,  in  turn,  are  grouped  into  resource  files,  which  correspond  to  the  resource 
forks  of  GS/OS  files.  A  given  resource  file  may  contain  one  or  more  resources  of  various 
format.  An  application  that  uses  resources  may  store  those  resources  in  its  own  resource 
file,  or  may  access  resources  in  a  resource  file  that  is  not  directly  associated  with  the 
program.  The  Resource  Manager  provides  routines  to  access  and  manipulate  resources  in  a 
resource  file. 

You  can  create  the  resource  fork  for  your  program  in  a  variety  of  ways.  Resource  compilers 
convert  text-based  resource  definitions  into  resources  in  a  valid  resource  file.  You  can  use 
an  existing  resource  compiler,  or  you  can  create  your  own.  Alternatively,  you  can  write  a 
program  that  creates  a  resource  file  and  its  resources,  using  Resource  Manager  tool  calls. 
Finally,  resource  editors  allow  you  to  create  resources  interactively. 


Identifying  resources 

Programs  identify  resources  with  a  resource  specification  consisting  of  a  resource  type 
and  a  resource  ID  number.  The  resource  type  (or  just  type)  defines  a  class  or  group  of 
resources  that  share  a  common  format.  The  resource  ID  (or  just  ID)  uniquely  identifies  a 
specific  resource  of  a  given  type.  Taken  together,  the  resource  type  and  ID  completely 
identify  the  resource  and  define  its  format.  The  ID  for  a  resource  must  be  unique  within 
the  context  of  its  type;  however,  the  same  ID  number  may  be  used  for  resources  of 
different  type. 


Chapter  45  Resource  Manager      45-5 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Resource  types 

The  resource  type  defines  a  class  of  resources  that  share  a  common  format.  The  system 
defines  several  standard  types  for  resources  used  to  interact  with  system  or  toolbox 
functions.  These  standard  types  and  the  formats  of  their  associated  resources  are 
documented  in  Appendix  E,  "Resource  Types,"  in  this  book.  In  addition,  your  program 
may  define  unique  resource  types  for  its  custom  resources.  Since  the  Resource  Manager 
knows  nothing  about  the  format  or  content  of  the  resources  it  manages,  you  have 
complete  freedom  to  define  the  resources  you  need. 

The  resource  type  is  a  word  value.  The  following  table  summarizes  valid  resource  type 
values: 


Type  value  range 


Use 


$0000 

$0001  through  $7FFF 

$8000  through  $FFFF 


Invalid  resource  type;  do  not  use 
Available  for  application  use 
Reserved  for  system  use 


Resource  IDs 

The  resource  ID  uniquely  identifies  a  particular  resource  of  a  given  type  in  a  resource  file. 
Every  resource  in  a  resource  file  must  have  an  ID  value  that  is  unique  within  the  context  of 
its  resource  type.  Resources  of  different  type  may,  however,  have  the  same  ID  value. 

The  resource  ID  is  a  long  value.  Even  though  the  resource  ID  is  only  meaningful  in  the 
context  of  a  given  resource  type,  the  system  does  place  restrictions  on  the  ID  values  you 
can  assign.  The  following  table  summarizes  the  allowable  ranges  for  ID  values: 


ID  value  range 


Use 


$00000000 

$00000001  through  $07FEFFFF 
$07FF0000  through  $07FFFFFF 
$08000000  through  $FFFFFFFF 


Invalid  resource  ID;  do  not  use 
Available  for  application  use 
Reserved  for  system  use 
Invalid  values;  do  not  use 


When  creating  a  new  resource,  use  the  uniqueResourceiD  tool  call  to  obtain  a  resource 
ID.  The  Resource  Manager  will  allocate  a  new,  unique  resource  ID  for  you.  You  can  force 
the  ID  to  fall  within  a  desired  range,  in  order  to  group  resources  by  resource  ID  within 
resource  type.  Each  ID  range  contains  65,535  possible  values.  The  ID  range  value  provides 
the  high-order  word  of  the  long-word  resource  ID.  The  following  table  summarizes  the 
allowable  ranges: 
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ID  Range 


Lowest  possible  ID  returned 


Highest  possible  ID  returned 


$0000 

$00000001  (NIL  is  invalid) 

$0000FFFF 

$0001 

$00010000 

$0001FFFF 

$0002 

$00020000 

$0002FFFF 

(and  so  on) 

$07FE  $07FE0000  $07FEFFFF 

$07FF  Reserved  for  system  use 

$0800-$FFFE      Invalid  range  values 

$FFFF  $00000001  $07FEFFFF 

(directs  Resource  Manager  to  allocate  from  any  application  range) 


Resource  Names 

As  an  alternative  to  identifying  a  resource  of  a  given  type  by  an  ID,  you  may  choose  to 
assign  it  a  resource  name.  Your  application  may  then  use  the  resource  type  and  name 
combination  to  uniquely  identify  the  resource.  In  some  cases,  this  may  be  more  handy 
than  using  the  numeric  ID.  The  resource  name  must  be  unique  within  the  context  of  a  given 
resource  type.  You  should  note  that  the  Resource  Manager  does  not  provide  call-level 
support  for  resource  names.  However,  the  rResName  resource  ($8014)  defines  the 
standard  layout  for  resource  names.  If  you  choose  to  use  resource  names,  or  you  use 
developer  tools  that  support  named  resources,  you  should  be  careful  to  use  the  standard 
data  structures  for  defining  those  names. 
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Using  resources 

In  most  cases,  applications  only  use  the  Resource  Manager  indirectly,  by  using  other  tool 
sets  that,  in  turn,  use  resources  to  store  their  data  structures.  Even  if  your  program  defines 
resources,  either  for  its  own  data  or  for  data  to  be  used  by  the  system,  it  will  have  to  issue 
only  a  few  Resource  Manager  calls  to  use  those  resources.  However,  programs  that  create 
and  manipulate  resources  and  resource  files  must  use  far  more  Resource  Manager 
functionality.  The  next  several  paragraphs  describe  the  steps  your  program  must  follow  in 
order  to  use  its  predefined  resources. 

1 .  Unlike  most  other  tool  sets,  your  program  does  not  have  to  start  the  Resource 
Manager.  At  startup  time,  the  system  automatically  loads  and  initializes  the  Resource 
Manager  from  the  RESOURCE.MGR  file  in  the  SYSTEM.SETUP  directory  of  the  boot 
disk.  The  Resource  Manager  then  opens  the  system  resources  file,  SYS.RESOURCES  in 
the  SYSTEM.SETUP  directory,  if  it  is  present. 

2.  To  use  the  Resource  Manager,  you  program  must  log  in,  using  the  Resourcestartup 
tool  call.  This  call  informs  the  Resource  Manager  that  your  program  is  going  to  be  using 
its  services.  As  an  alternative,  your  program  may  issue  the  Tool  Locator 
StartUpTools  call. 

3.  Issue  the  openResourceFile  tool  call  to  open  each  resource  file  for  your 
application.  If  your  program  issued  the  Tool  Locator  start  up  Tools  call,  then  it 
need  not  explicidy  open  its  resource  fork  before  trying  to  use  resources  located  there. 
If,  on  the  other  hand,  your  program  used  the  Resourcestartup  tool  call,  then  it 
must  issue  an  openResourceFile  call  for  its  resource  fork  before  accessing  any 
resources  stored  there. 

4.  As  part  of  termination  processing,  call  ResourceShutDown  to  log  out  from  the 
Resource  Manager.  The  Resource  Manager  will  automatically  close  any  open  resource 
files.  Once  your  program  has  issued  a  ResourceShutDown  call,  it  should  not  make 
any  other  Resource  Manager  calls,  except  for  Resourcestartup. 
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Resource  attributes 


Every  resource  has  an  associated  set  of  attributes  that  define  the  current  state  of  the 
resource  as  well  as  limits  on  how  the  resource  can  be  used.  The  Resource  Manager  stores 
these  attributes  in  an  attributes  flag  word  (or  Attributes  word)  for  the  resource 
(specifically,  the  resAttr  field  in  the  resource  reference  record).  Your  program  can  read 
and  write  this  attribute  word  by  means  of  the  GetResourceAttr  and 
SetResourceAttr  tool  calls.  In  addition,  the  MarkResourceChange  tool  call 
provides  a  convenient  mechanism  for  changing  the  setting  of  the  changed  flag  for  the 
resource,  which  indicates  whether  the  resource  has  been  changed  since  it  was  read  from 
disk. 

Many  of  the  attributes  govern  the  type  of  memory  used  to  store  the  resource  when  the 
Resource  Manager  reads  it  in  from  disk.  These  attributes  directly  correspond  to  flags  in 
the  Memory  Manager  NewHandie  tool  call  memory  Attributes  word.  When  it  allocates 
memory  for  a  resource  to  be  loaded  from  disk,  the  Resource  Manager  masks  out  the  other 
bits  and  passes  the  Attributes  word  to  the  NewHandie  call.  See  the  NewHandie  tool 
description  in  Chapter  12,  "Memory  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for  the 
format  and  content  of  the  memory  Attributes  word. 

The  following  table  describes  the  content  of  the  attribute  word  for  a  resource: 

attrLocked  Bit  15         Passed  to  Memory  Manager  NewHandie  tool  call 

when  memory  is  allocated  for  the  resource: 
1  -  Memory  for  resource  locked;  cannot  be  moved  or 
purged 

0  -  Memory  for  resource  not  locked 
Passed  to  Memory  Manager  NewHandie  tool  call 
when  memory  is  allocated  for  the  resource: 

1  -  Memory  for  resource  is  fixed  and  cannot  be  moved 

0  -  Memory  for  resource  need  not  be  fixed 
Must  be  set  to  0. 

Indicates  whether  the  resource  requires  a  resource 
converter  routine  (see  "Resource  converter  routines" 
later  in  this  chapter  for  more  information): 

1  -  Resource  requires  a  converter  routine 

0  -Resource  does  not  require  a  converter  routine 
resAbsLoad              Bit  10         Governs  whether  the  resource  must  be  loaded  at  a 

specific  memory  location.  Resources  that  must  be 
loaded  at  an  absolute  location  must  be  created  by  a 
resource  editor  or  compiler. 

1  -  Resource  to  be  loaded  at  specific  location 

0  -  Resource  need  not  be  loaded  at  a  specific  location 


attrFixed 


Reserved 

resConverter 


Bit  14 


Bits  12-13 
Bit  11 
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attrPurge 


resProtected 


resPreLoad 


resChanged 


attrNoCross 


attrNoSpec 


attrPage 


Reserved 


Bits  8-9      Passed  to  Memory  Manager  NewHandie  tool  call 

when  memory  is  allocated  for  the  resource: 

11 -Purge  level  3 

10 -Purge  level  2 

01  -  Purge  level  1 

00 -Purge  level  0 
Bit  7  Indicates  whether  the  resource  is  write-protected.  If 

set  to  1,  then  applications  may  not  update  the 

resource  on  disk: 

1  -  Resource  is  write-protected 

0  -  Resource  is  not  write-protected 

Bit  6  Specifies  whether  the  Resource  Manager  should  load 

the  resource  into  memory  at  openResourceFiie 
time.  If  set  to  1,  then  this  resource  will  be  loaded  into 
memory  when  the  resource  file  is  opened,  rather  than 
when  the  resource  itself  is  accessed: 

1  -  Preload  the  resource 

0  -  Do  not  preload  the  resource 

Bit  5  Indicates  whether  the  resource  has  been  changed.  If 

set  to  1  for  a  non-write-protected  resource,  the 
Resource  Manager  will  update  the  resource  on  disk  at 
CloseResourceFile  time: 

1  -  Resource  has  been  changed  in  memory,  and 
therefore  differs  from  the  version  stored  on  disk 

0  -  Resource  has  not  been  changed  in  memory 
Bit  4           Passed  to  Memory  Manager  NewHandie  tool  call 

when  memory  is  allocated  for  the  resource: 

1  -  Memory  may  not  cross  bank  boundary 

0  -  Memory  may  cross  bank  boundary 

Bit  3  Passed  to  Memory  Manager  NewHandie  tool  call 

when  memory  is  allocated  for  the  resource: 

1  -  May  not  use  special  memory 

0  -  May  use  special  memory 

Bit  2  Passed  to  Memory  Manager  NewHandie  tool  call 

when  memory  is  allocated  for  the  resource: 

1  -  Memory  must  be  page-aligned 

0  -  Memory  need  not  be  page-aligned 
Bits  0-1      Must  be  set  to  0 
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Resource  file  format 

A  resource  file  is  not  a  file  in  the  strictest  sense;  actually,  it  is  one  of  two  parts,  or  forks,  of 
a  GS/OS  file.  Every  file  has  a  resource  fork  and  a  data  fork,  either  of  which  may  be  empty. 
The  data  fork  contains  information  for  the  application  as  well  as  the  application  code 
itself,  and  is  formatted  according  to  the  needs  of  the  application.  Programs  manipulate 
data  in  the  data  fork  with  GS/OS  file  system  calls. 

The  Resource  Manager  defines  the  format  of  the  resource  fork.  Programs  read  and 
manipulate  resources  with  Resource  Manager  tool  calls.  As  a  result,  applications  do  not 
need  to  know  the  format  of  the  resource  fork  to  use  the  resources  stored  there.  You  can 
create  resources  and  load  them  into  a  resource  file  with  the  aid  of  a  Resource  Editor,  or 
with  whatever  tools  are  available  in  your  development  environment. 

A  resource  file  consists  primarily  of  resource  data  and  a  resource  map.  The  resources 
themselves  comprise  the  resource  data.  The  resource  map  is  a  directory  to  those 
resources,  containing  both  location  and  size  information.  Each  entry  in  the  map  on  disk 
contains  the  offset  of  the  resource  into  the  file;  in  memory,  the  entry  contains  a  handle  to 
the  resource  if  it  is  loaded.  The  Resource  Manager  reads  the  resource  map  into  memory  at 
resource  file  open  time,  and  maintains  it  in  memory  until  the  file  is  closed. 


Resource  File  IDs 

an  application  opens  a  resource  file,  the  Resource  Manager  assigns  that  open  file  a  file  ID, 
which  identifies  the  file  to  the  Resource  Manager.  Every  open  resource  file  has  a  file  ID 
that  is  unique  in  the  entire  system.  Many  Resource  Manager  tool  calls  require  the  file  ID  in 
order  to  identify  the  resource  file  to  be  accessed.  The  file  ID  for  the  system  resource  file  is 
always  $0001  (sysFiieiD). 

The  openResourceFiie  tool  call  returns  the  file  ID  for  a  resource  file.  Note  that  the  file 
ID  does  not  correspond  to  the  GS/OS  file  reference  number.  Use  the 
GetopenFiieRef  Num  Resource  Manager  tool  call  to  obtain  the  GS/OS  file  number  for  a 
resource  file. 
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Resource  file  search  sequence 

As  your  program  opens  resource  files,  the  Resource  Manager  adds  those  files  to  the  head 
of  the  resource  file  search  chain  for  your  application.  The  Resource  Manager  uses  this 
search  chain  for  many  of  its  operations,  such  as  locating  a  resource.  The  system  resource 
file  is  always  the  last  file  in  the  search  sequence.  When  it  runs  the  search  chain,  the 
Resource  Manager  first  checks  all  files  in  the  application  chain,  then  checks  in  the  system 
resource  file,  if  one  is  defined. 

You  control  the  application  file  search  sequence  by  the  order  in  which  your  program  opens 
its  resource  files.  For  example,  if  your  program  issues  the  following  tool  calls: 

OpenResourceFile        File  A 

OpenResourceFile        File  B 

OpenResourceFile        File  C 

Resource  Manager  builds  the  following  search  chain  for  your  application: 


L .  File  A  f*- 


System  File 


Search 


File  B 


File  C 


The  most  recently  opened  file  (in  this  example,  File  C)  is  referred  to  as  the  current  resource 
file  (or  simply,  the  current  file).  It  is  also  called  the  first  resource  file  (or  first  file),  since  it 
is  first  file  accessed  during  a  search.  The  least  recendy  opened  application  resource  file 
(File  A)  is  called  the  last  resource  file  (or  last  file),  because  it  is  the  last  application  file  to 
be  searched. 


45-12     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  1IGS  Toolbox  Reference,  Volume  3  Beta  Draft  30  August  1989 


During  a  search,  which  happens  on  nearly  every  Resource  Manager  tool  call  that  accepts 
resource  type  and  ID  arguments,  the  Resource  Manager  starts  with  the  current  file,  and 
searches  through  the  chain  until  it  either  finds  the  desired  resource  or  exhausts  the  file  list. 
Note  that  the  search  stops  with  the  first  occurrence  of  a  matching  resource;  a  second 
instance  of  a  resource  with  the  same  ID  and  type  will  not  be  found  unless  your  application 
asserts  further  control  over  the  resource  search  sequence. 

The  Resource  Manager  provides  tool  calls  that  allow  your  program  to  control  the  search 
sequence  for  the  resource  file  chain.  The  setcurResourceFile  tool  call  changes  the 
current  resource  file,  so  that  any  resource  file,  including  the  System  file,  can  be  the  first  file 
searched,  though  the  search  still  terminates  when  the  Resource  Manager  either  finds  the 
desired  resource,  or  hits  the  end  of  the  file  chain.  The  setResourceFiieDepth  tool  call 
controls  the  number  of  files  the  Resource  Manager  will  search  before  giving  up.  By  using 
these  calls,  your  program  can  fine-tune  resource  searches  for  performance  or  can  inhibit 
access  to  some  resource  files  for  some  searches. 


Resource  file  layout  and  data  structures 

This  section  describes  the  format  of  a  resource  file  on  disk.  This  information  is  intended 
only  for  application  programmers  who  are  writing  tools  to  create,  delete,  or  edit  resources 
in  the  resource  fork. 

Figure  45-1  shows  the  internal  layout  of  the  resource  fork  of  a  file.  The  resource  file  header 
is  the  only  data  block  that  resides  at  a  fixed  location  in  the  fork;  it  is  always  the  first  data 
item  in  the  fork.  Along  with  other  control  information,  the  resource  file  header  contains 
the  file  offset  to  the  resource  map.  The  map,  in  turn,  contains  location  and  size 
information  for  each  resource  contained  in  the  file. 
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Figure  45-1      Resource  file  internal  layout 


Always  first  — 
in  resource  fork 


Any  place  in  — 
file  after  header 


Any  place  in  — 
file  after  header 


Any  place  in  — 
file  after  header 


Any  place  in  — 
file  after  header 


Resource  file  header 


rFileToMap 


Resource 


Resource  map 


I\    J 


Resource 


Resource 


The  Resource  Manager  controls  the  relative  positions  of  all  elements  of  the  resource  fork. 
It  will  move  or  resize  the  map  or  resources  as  required.  Therefore,  your  program  should 
never  rely  on  the  location  of  any  element  in  the  fork,  except  for  the  resource  file  header. 

The  following  sections  present  the  format  of  the  resource  file  header,  resource  map,  and 
their  associated  data  structures  in  greater  detail.  These  descriptions  present  version  0 
layout  infomation.  Future  system  releases  may  support  other  versions  with  different 
layouts.  Your  program  should  check  the  value  in  the  rFiieversion  field  in  the  resource 
file  header  before  manipulating  a  resource  file. 
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Resource  file  header 

The  resource  file  header  is  the  first  data  block  in  every  resource  fork,  and  has  the  following 
format: 


$00 

rFileVersion 

— 

Long 

$04 

rFileToMap 

~ 

Long 

$08 

~ 

rFileMapSize 

Long 

$0C 

rFi leMemo 

128  Bytes 

rFileVersion  Version  number  defining  layout  of  resource  file.  Currently,  only  version 
0  is  supported.  This  field  allows  IIGS  resource  files  to  be  distinguished 
from  Macintosh  resource  files;  the  first  long  in  Macintosh  resource  files 
must  have  a  value  that  is  greater  than  127. 

rFileToMap        Offset,  in  bytes,  to  beginning  of  the  resource  map.  This  offset  starts 
from  the  beginning  of  the  resource  file. 

rFileMapSize    Size,  in  bytes,  of  the  resource  map. 

rFiieMemo  Reserved  for  application  use.  The  Resource  Manager  does  not  provide 

any  facility  for  reading  or  writing  this  field.  Your  program  must  use 
GS/OS  file  system  calls  to  access  the  rFiieMemo  field. 
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Resource  map 

The  resource  map  provides  indexes  to  the  resources  stored  in  the  resource  file,  and  is 
formatted  as  follows: 


$00 

$04 
$06 

$0A 

$0E 
$10 
$12 
$14 

$18 

$1C 

$1E 
$20 

$xx 


—     mapOffset     — 


mapNext 


mapFlag 


mapSize 


mapToIndex 


mapFileNum  — 


mapID 


—   mapIndexSize    — 


mapIndexUsed 


-     mapFreeListSize     — |    Word 

Word 


mapFreeListUsed 


Long 
Word 
Long 

Long 

Word 
Word 
Word 

Long 
Long 


mapFreeList         \  Array  ofresource  free  blocks 


mapindex  \  Array  of  resource  reference  records 


mapNext  Handle  to  resource  map  for  next  resource  file  in  the  search  chain.  Set 

to  NIL  if  last  file  in  chain.  This  field  is  only  valid  when  the  map  is  in 
memory. 
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mapFlag  Contains  control  flags  defining  the  state  of  the  resource  file: 

Reserved  bits  2-15     Set  to  0 

mapchanged  bit  1  Indicates  whether  the  resource  map  has  been 

modified,  and  must  therefore  be  written  to  disk 

when  the  file  is  closed: 

1  -  Map  changed 

0  -  Map  not  changed 
Reserved  bit  0  Set  to  0 

mapof  f  set  Offset,  in  bytes,  to  the  resource  map  from  the  beginning  of  the 

resource  file, 

mapsize  Size,  in  bytes,  of  the  resource  map  on  disk.  Note  that  the  memory 

image  of  the  map  may  have  a  different  size  due  to  resource  or 
resource  file  changes  during  program  execution. 

mapToindex        Offset,  in  bytes,  from  beginning  of  map  to  the  beginning  of  the 
mapindex  array  of  resource  reference  records. 

mapFiieNum        GS/OS  file  reference  number.  This  field  is  valid  only  in  memory. 

mapiD  Resource  Manager  file  ID  for  the  open  resource  file.  This  field  is  valid 

only  in  memory. 

mapindexsize    Total  number  of  resource  reference  records  in  mapindex. 

mapindexused    Number  of  used  resource  reference  records  in  mapindex. 

mapFreeListSize 

Total  number  of  resource  free  blocks  in  mapFreeList. 

mapFreeListUsed 

Number  of  used  resource  free  blocks  in  mapFreeList. 

mapFreeList      Array  of  resource  free  blocks,  which  describe  free  space  in  the 
resource  file. 

mapindex  Array  of  resource  reference  records,  which  contain  control  information 

about  the  resources  in  the  resource  file. 
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Resource  free  block 

The  resource  free  block  describes  a  contiguous  area  of  free  space  in  the  resource  file.  The 
resource  map  contains  a  variable-sized  array  of  these  blocks  at  mapFreeList.  Note  that 
each  resource  file  has  at  least  one  resource  free  block,  defining  free  space  from  the  end  of 
the  resource  file  to  $FFFFFFFF.  Each  resource  free  block  has  the  following  format: 


$00 


$04 


-     blkOffset 


blkSize 


Long 


Long 


bikoffset  Offset,  in  bytes,  to  the  free  block  from  the  start  of  the  resource  fork. 

A  NIL  value  indicates  the  end  of  the  used' blocks  in  the  array. 

biksize  Size,  in  bytes,  of  the  free  block  of  space. 
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Resource  reference  record 

The  resource  reference  record  contains  control  information  about  a  resource.  The  resource 
map  contains  a  variable-sized  array  of  these  blocks,  starting  at  the  location  specified  in 
mapToindex.  Each  resource  reference  record  has  the  following  format: 


$00 

resType 

- 

Word 

$02 

^ 

resID 

: 

Long 

$06 

resOffset 

: 

Long 

$0A 

- 

resAttr 

Word 

$0C 

_ 

resSize 

Long 

$10 

- 

resHandle 

Long 

resType  Resource  type.  NIL  value  indicates  last  used  entry  in  the  array. 

resiD  Resource  ID. 

resOffset  Offset,  in  bytes,  to  the  resource  from  the  start  of  the  resource  file. 

resAttr  Resource  attributes.  See  "Resource  attributes"  earlier  in  this  chapter 

for  bit  flag  definitions. 

resSize  Size,  in  bytes,  of  the  resource  in  the  resource  file.  Note  that  the  size  of 

the  resource  in  memory  may  differ,  due  to  changes  made  to  the 
resource  by  application  programs  or  by  resource  converter  routines. 

resHandle  Handle  of  resource  in  memory.  NIL  value  indicates  that  the  resource 

has  not  been  loaded  into  memory.  Your  program  can  determine  the  in- 
memory  size  of  the  resource  by  examining  the  size  of  this  handle. 
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Resource  converter  routines 

The  Resource  Manager  supports  the  concept  of  resource  converter  routines.  Converter 
routines  format  resources  for  access  by  your  program,  allowing  the  memory  format  of  a 
resource  to  differ  from  its  disk  representation.  These  routines  can  be  used,  for  example, 
to  store  resources  in  a  compressed  form  on  disk,  to  reformat  common  resources  for 
different  programs  or  operating  environments,  or  to  perform  code  relocation. 

When  loading  or  unloading  a  resource,  the  Resource  Manager  determines  whether  to 
invoke  a  converter  routine  by  examining  the  resConverter  flag  in  the  Attributes  word 
for  the  resource.  If  that  flag  is  set  to  1,  indicating  that  the  resource  must  be  converted 
before  being  read  or  written,  the  Resource  Manager  invokes  the  appropriate  converter 
routine  for  the  resource  type.  The  converter  routine  may  then  reformat  the  resource  in  any 
way  it  chooses. 

Your  program  registers  a  converter  routine  with  the  ResourceConverter  tool  call.  At 
that  time,  your  program  must  specify  the  resource  type  to  be  handled  by  the  converter 
routine.  One  converter  routine  may  handle  more  than  one  resource  type;  your  program 
must  issue  separate  ResourceConverter  tool  calls  for  each  type  to  be  converted. 

The  Resource  Manager  tracks  resource  converters  in  two  types  of  lists.  Each  application 
has  a  private  application  routine  list,  which  can  contain  up  to  10,922  entries.  In  addition, 
the  Resource  Manager  maintains  a  system  routine  list,  which  is  available  to  all 
applications.  When  searching  for  a  converter  routine  for  a  specific  resource  type,  the 
Resource  Manager  first  checks  the  application  list,  then  the  system  list.  As  a  result,  your 
program  can  override  a  standard  converter  routine  by  registering  a  routine  for  the  same 
resource  type  in  its  application  converter  routine  list.  Applications  should  never  log 
routines  into  or  out  of  the  system  list. 

When  the  Resource  Manager  invokes  a  converter  routine,  it  loads  the  stack  with  values 
specifying  the  operation  to  be  performed  and  any  needed  parameters.  Before  returning 
control  to  the  Resource  Manager,  the  converter  routine  should  set  a  condition  code  in  the 
A  register  (any  nonzero  value  indicates  an  error)  and  return  the  appropriate  result  value  on 
the  stack.  The  following  sections  provide  detailed  descriptions  of  the  entry  and  exit 
conditions  for  each  converter  routine  operation. 

Note:  Not  all  resource  converters  support  conversion  when  resources  are  written  back 
to  disk.  The  supplied  code  resource  converter  only  functions  on  resource  read 
operations,  for  example.  Consequendy,  if  you  are  unsure  about  the  behavior  of  a  given 
resource  converter,  you  should  not  mark  converted  resources  changed,  since  the 
converter  may  write  them  back  to  disk  in  an  unexpected  format. 
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ReadResource 

Read  a  resource  from  disk  into  memory.  The  converter  routine  must  load  the  file  from 
disk  and  perform  any  necessary  reformatting. 

On  entry,  convertParam  contains  a  pointer  to  a  GS/OS  read  file  parameter  block  (see  the 
GS/OS  Reference  for  more  information  on  GS/OS  file  manipulation  and  data  structures). 
The  file  mark  is  set  to  the  beginning  of  the  file  and  the  block  is  set  to  read  the  entire 
resource  from  disk.  In  order  to  read  the  file,  your  program  can  do  the  following: 

pushlong    convertParam  Pointer  to  read  parameter  block 

pushword    $2012  GS/OS  read  command  code 

jsl         $E100B0  Call  GS/OS 
check  for  errors 

The  resPointer  field  contains  a  pointer  to  the  resource  reference  record,  which 
contains  location  and  size  information  about  the  resource  in  memory  (see  "Resource  file 
format"  earlier  in  this  chapter  for  information  on  the  format  and  content  of  the  resource 
reference  record).  Your  program  should  verify  that  the  number  of  bytes  loaded 
corresponds  to  the  size  of  the  resource  on  disk  (compare  res  size  value  to  the  size  of 
the  handle  that  received  the  resource).  Your  program  should  also  check  to  see  if  the 
resource  must  be  loaded  at  an  absolute  location  (resAbsLoad  flag  set  to  1  in  resAttr 
word  of  the  resource  reference  record).  If  so,  be  careful  to  convert  the  resource  into  the 
appropriate  location. 

If,  during  resource  conversion,  the  converter  routine  must  copy  the  resource  into  a 
different  handle,  the  routine  must  load  that  new  handle  into  the  resHandie  field  of  the 
resource  reference  record,  and  dispose  of  the  original  handle.  Upon  return,  the  handle  to 
the  converted  resource  should  retain  its  original  Memory  Manager  attributes  (locked,  and 
so  on). 

Upon  successful  completion,  the  converter  routine  should  return  a  NIL  Result  value.  In  case 
of  error,  the  routine  should  return  a  non-NIL  Result,  and  must  free  the  memory  referenced 
by  the  resHandie  field  in  the  resource  reference  record,  and  set  that  field  to  NIL. 
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Parameters 

Stack  before  call 


Previous  contents 


Space 


convertCommand 


convertParam  - 


resPointer 


Stack  after  call 


Long— Space  for  result 

Word— Command  to  be  performed  (will  be  0:  readResource) 

Long— Pointer  to  GS/OS  read  file  parameter  block 

Long— Pointer  to  resource  reference  record 
<— SP 


Previous  contents 


Result 


Long— NIL  if  successful;  error  code  if  error  (low-order  word) 
<— SP 
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WriteResource 

Write  a  resource  from  memory  onto  disk.  The  converter  routine  must  perform  any 
necessary  reformatting  and  write  the  file  to  disk. 

On  entry,  convertParam  contains  a  pointer  to  a  GS/OS  write  file  parameter  block  (see 
\hzGS/OS  Reference  for  more  information  on  GS/OS  file  manipulation  and  data 
structures).  The  file  mark  is  set  to  the  beginning  of  the  file  on  disk  and  the  block  is  set  to 
write  the  entire  resource.  Before  issuing  a  writeResource  command,  the  Resource 
Manager  will  determine  the  amount  of  disk  space  required  for  the  resource  by  calling  the 
returnDisksize  function  in  the  converter  routine. 

In  order  to  write  the  file,  your  program  can  do  the  following: 

pushlong    convertParam      Pointer  to  read  parameter  block 
pushword    $2013  GS/OS  write  command  code 

jsl         $E100B0  Call  GS/OS 

check  for  errors 

The  resPointer  field  contains  a  pointer  to  the  resource  reference  record,  which 
contains  location  and  size  information  about  the  resource  in  memory  (see  "Resource  file 
format"  earlier  in  this  chapter  for  information  on  the  format  and  content  of  the  resource 
reference  record).  The  Resource  Manager  will  dispose  of  the  handle  to  the  resource  after 
calling  writeResource. 

This  function  must  return  a  NIL  Result  value. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


convertCommand 


-  convertParam  - 


resPointer 


Long— Space  for  result 

Word— Command  to  be  performed  (will  be  2:  writeResource) 

Long— Pointer  to  GS/OS  write  file  parameter  block 

Long— Pointer  to  resource  reference  record 
<— SP 
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Stack  after  call 


Previous  contents 


Result 


Long— Must  be  set  to  NIL 
<— SP 
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ReturnDiskSize 

Determines  the  amount  of  space  a  resource  will  require  on  disk,  and  returns  that  value  to 
the  caller.  Note  that  this  call  is  not  valid  for  resources  that  are  loaded  into  absolute 
memory,  since  the  size  of  these  resources  cannot  change. 

The  convertParam  parameter  is  undefined. 

The  resPointer  field  contains  a  pointer  to  the  resource  reference  record,  which 
contains  location  and  size  information  about  the  resource  in  memory  (see  "Resource  file 
format"  earlier  in  this  chapter  for  information  on  the  format  and  content  of  the  resource 
reference  record). 

On  exit,  Result  contains  the  amount  of  disk  space  required  to  store  the  resource,  in  bytes. 
If  this  new  size  differs  from  the  original  file  size,  the  Resource  Manager  frees  the  old  space 
and  allocates  a  new  file. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


convertCommand 


-  convertParam  - 


resPointer 


Long— Space  for  result 

Word— Command  to  be  performed  (will  be  4:  returnDisksize) 

Long— Undefined 

Long— Pointer  to  resource  reference  record 
<— SP 


Stack  after  call 


Previous  contents 


Result 


Long— Bytes  of  disk  space  required  to  store  resource 
<— SP 
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Application  switchers  and  desk  accessories 

Desk  accessories  and  application-switching  programs  must  be  careful  to  preserve  the 
state  of  the  Resource  Manager  before  using  its  facilities.  The  Resource  Manager  provides 
tool  calls  that  allow  such  programs  to  switch  the  currendy  active  Resource  Manager 
application.  The  GetcurResourceApp  tool  call  returns  the  User  ID  of  the  application 
that  is  currendy  using  the  Resource  Manager.  This  call  returns  a  special  value  if  the  Resource 
Manager  is  not  in  use.  The  setcurResourceApp  tool  call  changes  the  current 
application,  by  loading  a  new  User  ID  value.  It  is  the  responsiblity  of  the  code  doing  the 
switch  to  use  these  calls. 

In  the  following  example,  the  Resource  Manager  is  already  active  and  the  application 
switcher  has  previously  registered  itself  with  the  Resource  Manager  with  the 
Resourcestartup  tool  call.  The  switching  program  must  save  the  User  ID  of  the 
program  that  is  currendy  using  the  Resource  Manager  before  it  issues  any  other  Resource 
Manager  tool  calls: 


pha  ;  space  for  result  from  GetCurResourceApp 

GetcurResourceApp 

get  current  app  user  ID,  save  on  stack 
pushword  myUserlD  ;  pass  my  user  ID  to  Resource  Manager 
SetCurResourceApp 

switch  to  my  resources  and  files 


SetCurResourceApp 


(return  to  caller) 


restore  original  application  user  ID 
(saved  on  stack  after  GetCurResourceApp 
tool  call) . 
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In  the  case  where  your  program  must  first  log  into  the  Resource  Manager,  it  must  issue  the 
Resourcestartup  tool  call  before  calling  any  other  Resource  Manager  functions: 
;  (on  entry  to  desk  accessory  task  handler) 


NoResMgr 


Prime  for  FALSE  if  Resource  Manager 

is  not  active 
check  for  active  Resource  Manager 

Exit  if  Resource  Manager  not  active 

Space  for  result 


pushword  #0 

ResourceStatus 

pla 

beq   NoResMgr 

pha 
GetCurResourceApp 

get  current  app  user  ID,  save  on  stack 
pushword  myUserlD  ;  pass  my  user  ID  to  Resource  Manager 
SetCurResourceApp 

switch  to  my  resources  and  files 


SetCurResourceApp 


restore  original  application  user  ID 
(saved  on  stack  after  GetCurResourceApp 
tool  call) . 


(return  to  caller) 
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Resource  Manager  housekeeping  routines 

This  section  discusses  the  standard  housekeeping  routines,  in  call  number  order. 


ResourceBootlnit     $011E 

Initializes  the  Resource  Manager. 

▲  Warning       An  application  must  never  make  this  call,  a 

Parameters  The  stack  is  not  affected  by  this  call.  There  are  no  input  our  output 

parameters. 

Errors  None 

C  Call  must  not  be  made  by  an  application. 
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ResourceStartUp     $021E 

Notifies  the  Resource  Manager  that  an  application  wishes  to  open  and  use  its  own 
resource  files.  Unlike  other  tool  set  startup  calls,  this  call  is  not  required  in  all 
circumstances.  If  your  application  only  uses  system  resources  (located  in  the  system 
resource  file),  then  it  does  not  have  to  issue  a  ResourceStartUp  tool  call.  On  the  other 
hand,  if  your  application  uses  non-system  resources,  then  it  must  issue  this  tool  all  prior 
to  opening  those  resource  files. 

If  your  application  issues  this  call,  then  it  must  issue  the  ResourceShutDown  tool  call 
before  quitting. 

Note  that  the  Tool  Locator  start upToois  tool  call  automatically  starts  the  Resource 
Manager. 

Parameters 

Stack  before  call 


Previous  contents 


userlD 


Stack  after  call 


Word— Application's  User  ID  (obtained  at  program  start  time) 
<— SP 


Previous  contents 


Errors 


<— SP 
Memory  Manager  errors 


Returned  unchanged 


extern  pascal  void  ResourceStartUp (userlD) 
Word      userlD; 
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ResourceShutDown     $031E 

Notifies  the  Resource  Manager  that  an  application  is  finished  using  its  own  resource  files. 
The  Resource  Manager  updates,  closes,  and  frees  memory  for  any  open  resource  files. 
Unlike  other  tool  set  shutDown  calls,  the  Resource  Manager  is  still  active  after  this  call. 
However,  after  calling  ResourceShutDown,  your  application  can  only  access  the  system 
resource  file. 

If  your  application  called  ResourceStartUp,  then  it  must  issue  a  ResourceShutDown 
call  before  quitting. 

Parameters  The  stack  is  not  affected  by  this  call.  There  are  no  input  or  output 

parameters. 

Errors  None 

C  extern  pascal  void  ResourceShutDown () ; 
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ResourceVersion     $04lE 

Retrieves  the  Resource  Manager  version  number.  The  versionlnfo  result  will  contain  the 
information  in  the  standard  format  defined  in  Appendix  A,  "Writing  Your  Own  Tool  Set," 
in  Volume  2  of  the  Toolbox  Reference. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


versionlnfo 


Errors 
C 


None 


Word— Resource  Manager  version  number 
<— SP 


extern  pascal  Word  ResourceVersion () ; 
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ResourceReset     $051E 

Resets  the  Resource  Manager;  issued  only  when  the  system  is  reset. 

A  Warning       An  application  must  never  make  this  call,  a 

Parameters  The  stack  is  not  affected  by  this  call.  There  are  no  input  our  output 

parameters. 

Errors  None 

C  Call  must  not  be  made  by  an  application. 
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ResourceStatus     $06lE 

Returns  a  flag  indicating  whether  the  Resource  Manager  is  active.  If  the  Resource  Manager 
loaded  and  initialized  successfully  at  system  startup,  then  this  function  returns  a  value  of 
TRUE.  If  the  Resource  Manager  did  not  successfully  load  or  initialize,  then  the  Tool 
Locator  returns  a  f  uncNotFoundErr  error  code  ($0002). 


♦  Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  ResourceStatus,  your  program  need  only  check 
the  value  of  the  returned  flag.  If  the  Resource  Manager  is  not  active,  the  returned  value 
will  be  FALSE  (NIL). 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


activeFlag 


Word— BOOLEAN;  TRUE  if  Resource  Manager  is  active 
<— SP 

Errors  $0002        f  uncNotFoundErr  Resource  Manager  not  active 

C  extern  pascal  Word  ResourceStatus () ; 


Chapter  45  Resource  Manager    45-33 


Apple  11GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Resource  Manager  tool  calls 

This  section  discusses  the  Resource  Manager  tool  calls,  in  call  name  order. 


AddResource     $0C1E 

Adds  a  resource  to  the  current  resource  file.  The  Resource  Manager  marks  the  new  resource 
as  changed  and  will  write  the  new  resource  to  disk  when  the  file  is  updated.  Your  program 
specifies  the  attributes  of  the  new  resource  in  a  flag  word  passed  to  AddResource. 
Some  of  these  attributes  control  how  memory  is  allocated  for  the  new  resource  when  it  is 
loaded  by  an  application,  others  govern  Resource  Manager  processing.  For  more 
information  about  the  various  attributes,  see  "Resource  attributes"  earlier  in  this  chapter. 

Parameters 

Stack  before  call 


Previous  contents 


resourceHandle  - 


resourceAttr 


resourceType 


resourcelD 


Long— Handle  of  resource  in  memory 

Word— Attributes  of  the  resource 
Word— Type  for  resource 

Long— ID  for  resource 

<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1E04 
$1E05 


<— SP 

resNoCurFile 
resDupID 


$1E0E         resDiskFull 
WriteResource  errors 
Memory  Manager  errors 
GS/OS  errors 


There  is  no  current  resource  file 
Another  resource  in  the  current 
file  is  using  this  ID 
Volume  full 
Returned  unchanged 
Returned  unchanged 
Returned  unchanged 
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resourceHandle 


resourceAttr 

resourceType 
resourcelD 


extern  pascal  void  AddResource (resourceHandle, 

resourceAttr,  resourceType,  resourcelD) ; 

Long      resourceHandle,  resourcelD; 
Word      resourceAttr,  resourceType; 

Specifies  the  memory  location  and  size  of  the  resource  to  be  added 
to  the  current  resource  file.  If  the  handle  is  empty,  AddResource 
creates  a  resource  with  zero  length.  Never  pass  a  handle  that  was 
created  by  the  Resource  Manager,  unless  the  resource  in  that  handle 
has  been  detached  (see  DetachResource  tool  call). 

If  resAbsLoad  in  resourceAttr\s  set  to  1,  then  the  Resource  Manager 
obtains  the  size  of  the  resource  from  the  mapsize  field  in  the 
resource  map. 

Bit  flags  defining  the  attributes  of  the  resource  to  be  added.  For 
information  about  the  specific  flags,  see  "Resource  attributes"  earlier 
in  this  chapter. 

Type  of  resource  to  be  added.  See  "Identifying  resources"  earlier  in 
this  chapter  for  details. 

ID  for  new  resource.  Must  be  unique  among  resources  of  the  same 
type.  See  "Identifying  resources"  earlier  in  this  chapter  for  more 
information.  Use  the  uniqueResourceiD  tool  call  to  obtain  a 
unique  ID. 
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CloseResourceFile     $0B1E 

Updates  a  specified  resource  file,  frees  any  memory  used  by  the  resource  map  for  the  file 
and  any  resources  currently  loaded,  and  closes  the  file.  Your  program  passes  the  file  ID  of 
the  resource  file  to  be  closed.  This  file  ID  is  obtained  from  the  openResourceFile  tool 
call. 

If  the  file  being  closed  is  the  current  resource  file,  the  next  file  in  the  resource  file  list 
becomes  the  current  resource  file.  Your  program  can  close  the  system  resource  file  by 
passing  the  system  file  ID  ($0001).  Note,  however,  that  some  tool  calls  require  system 
resources  (for  example,  the  system  stores  the  control  definition  procedure  for  icon 
button  controls  in  the  system  resource  file).  These  calls  will  not  work  if  you  close  the 
system  resource  file,  or  set  the  search  depth  so  shallow  that  the  system  resource  file  is 
inaccessible  (see  "setResourceFiieDepth"  later  in  this  chapter). 

♦   Note:  Your  program  does  not  need  to  issue  CloseResourceFile  calls  for  all  open 
resource  files  when  quitting.  The  ResourceShutDown  call  automatically  updates  and 
closes  any  open  resource  files. 


Parameters 

Stack  before  call 


Previous  contents 


fllelD 


Word— ID  of  open  resource  file;  NIL  to  close  all  open  files 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

GS/OS  errors 
WriteResource  errors 


Returned  unchanged 
Returned  unchanged 


extern  pascal  void  CloseResourceFile (filelD) 
Word      filelD; 
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CountResources     $221E 

Counts  the  number  of  resources  of  a  specified  type  in  all  resource  files  available  to  the 
calling  program  in  its  search  sequence.  Your  program  specifies  the  resource  type  to  be 
counted.  The  Resource  Manager  counts  all  resources  of  that  type  in  open  resource  files 
available  to  your  program,  including  the  system  resource  file. 


♦   Note:  This  call  can  be  very  slow  when  you  have  many  resources  or  resource  files.  Do  not 
issue  this  call  in  time-critical  procedures. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


Stack  after  call 


Long— Space  for  result 

Word— Resource  type  to  be  counted 

<— SP 


Previous  contents 


-  totalResources  - 


Errors 
C 


None 


Long— Number  of  resources  of  specified  type 
<— SP 


extern  pascal  Long  CountResources (resourceType) 


Word 


resourceType ; 
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CountTypes     $201E 

Counts  the  number  of  different  resource  types  in  all  resource  files  available  to  the  calling 
program  in  its  search  sequence,  including  the  system  resource  file. 

♦   Note:  This  call  can  be  very  slow  when  you  have  many  resources  or  resource  files.  Do  not 
issue  this  call  in  time-critical  procedures. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Word— Space  for  result 
<-SP 


Stack  after  call 


Previous  contents 


totalTypes 


Errors 
C 


Word— Number  of  different  resource  types 
<— SP 

Memory  Manager  errors  Returned  unchanged 

extern  pascal  Word  CountTypes  () ; 
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CreateResourceFile     $091E 

Initializes  a  resource  fork  with  no  resources.  If  necessary,  CreateResourceFile  will 
create  the  file  to  contain  the  resource  fork.  The  specific  actions  performed  by  this  call 
depend  upon  the  state  of  the  specified  input  file: 


No  file  of  specified  name 


File  with  no  resource  fork 
File  with  empty  resource  fork 
File  with  non-empty  resource  fork 

Parameters 

Stack  before  call 


Create  file  with  specified  auxType,  fileType, 

fileAccess,fileName.  Create  and  initialize 

resource  fork 

Create  and  initialize  resource  fork 

Initialize  resource  fork 

Return  resForkused  error 


Previous  contents 


auxType 


fileType 


fileAccess 


fileName 


Stack  after  call 


Previous  contents 


Errors 


Long— GS/OS  auxiliary  file  type  (used  only  if  file  does  not  exist) 

Word—GS/OS  file  type  (used  only  if  file  does  not  exist) 
Word— GS/OS  file  access  (used  only  if  file  does  not  exist) 

Long— Pointer  to  GS/OS  class  1  input  pathname  for  resource  file 

<— SP 


<— SP 

$1E01  resForkUsed 

GS/OS  errors 


Resource  fork  for  specified  file  is 
not  empty 
Returned  unchanged 


extern  pascal  void  CreateResourceFile (auxType, 
fileType,  fileAccess,  fileName) ; 

Long      auxType,  fileName; 
Word      fileType,  fileAccess; 
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DetachResource     $181£ 

Instructs  the  Resource  Manager  to  dispose  of  its  control  blocks  for  a  specified  resource. 
The  resource  itself  remains  in  memory;  the  calling  program  is  responsible  for  freeing  its 
handle.  The  resource  to  be  detached  must  be  marked  as  unchanged. 

This  call  can  be  used  to  copy  resources  between  different  resource  files.  After  issuing  the 
DetachResource,  add  the  resource  to  the  new  resource  file  by  calling  AddResource. 
After  issuing  the  AddResource  call,  the  Resource  Manager  is  again  responsible  for  the 
resource  handle. 

Parameters 

Stack  before  call 


Previous  contents 


resourceType 


resourcelD 


Word— Type  of  resource  to  be  detached 
Long— ID  of  resource  to  be  detached 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$1E06    resNotFound 
$1E0C    resHasChanged 


Specified  resource  cannot  be 

found 

Resource  has  been  changed  and 

has  not  been  updated 


extern  pascal  void  DetachResource (resourceType, 
resourcelD) ; 

Word      resourceType; 
Long      resourcelD; 


4540     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  1IGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


GetCurResourceApp     $141E 

Returns  the  User  ID  for  the  application  that  is  currently  using  the  Resource  Manager.  If  the 
Resource  Manager  is  not  in  use,  this  call  returns  the  Resource  Manager's  User  ID  ($401E). 
This  call  is  used  by  desk  accessories  and  application  switchers  (see  "Application  switchers 
and  desk  accessories"  earlier  in  this  chapter  for  more  information). 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


userlD 


Errors 
C 


None 


Word— User  ID  of  current  application;  $401E  if  none 
<— SP 


extern  pascal  Word  GetCurResourceApp () 
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GetCurResourceFile     $121E 

Returns  the  file  ID  of  the  current  resource  file.  This  call  returns  a  NIL  value  if  there  is  no 
current  file. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


filelD 


Errors 
C 


Word— File  ID  of  current  resource  file;  NIL  if  none 
<— SP 

$1E04        resNoCurFiie  No  current  'resource  file 

extern  pascal  Word  GetCurResourceFile () ; 
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GetlndResource     $231E 

Finds  a  resource  of  a  specified  type  by  means  of  its  index,  and  returns  the  resource  ID  for 
that  resource.  The  index  value  corresponds  to  the  position  of  the  desired  resource  among 
all  resources  of  the  specified  type  in  all  resource  files  available  to  the  calling  program  in  its 
search  sequence;  the  first  resource  is  number  1. 

Use  this  call  to  find  every  resource  of  a  given  type  by  repeatedly  issuing  the  call, 
incrementing  the  index  value  until  the  call  returns  resIndexRange. 

♦   Note:  This  call  can  be  very  slow  when  you  have  many  resources  or  resource  files.  Do  not 
issue  this  call  in  rime-critical  procedures. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


resourcelndex  - 


Stack  after  call 


Long — Space  for  result 
Word— Type  of  resource  to  find 
Long— Index  of  resource  to  find 
<— SP 


Previous  contents 


resourcelD 


Errors 


Long— ID  of  resource  matching  type  and  index 
<— SP 
$1E0A         resIndexRange 

Memory  Manager  errors 


Index  is  out  of  range  (no  resource 

found) 

Returned  unchanged 
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extern  pascal  Long  GetlndResource (resourceType, 
resourcelndex) ; 

Word      resourceType; 
Long      resourcelndex 
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GetlndType     $211E 

Finds  a  resource  type  value  by  means  of  its  index.  The  index  value  corresponds  to  the 
1-relative  position  of  the  desired  resource  type  among  all  types  in  all  resource  files 
available  to  the  calling  program  in  its  search  sequence. 

Use  this  call  to  find  every  resource  type  in  all  files  available  to  an  application  by  repeatedly 
issuing  the  call,  incrementing  the  index  value  until  the  call  returns  resIndexRange. 

♦   Note:  This  call  can  be  very  slow  when  you  have  many  resources  or  resource  files.  Do  not 
issue  this  call  in  time-critical  procedures. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


typelndex 


Stack  after  call 


Previous  contents 


resourceType 


Errors 


Word— Space  for  result 
Word— Index  of  type  to  find 
<— SP 


Word— Type  matching  index 
<— SP 


$1E0A         resIndexRange 
Memory  Manager  errors 


Index  is  out  of  range  (no  more 

types) 

Returned  unchanged 


extern  pascal  Word  GetlndType (typelndex) 
Word      typelndex; 
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GetMapHandle     $26lE 

Returns  a  handle  to  the  resource  map  for  a  specified  resource  file.  Your  program  specifies 
the  desired  resource  file  by  passing  its  file  ID  to  GetMapHandle.  This  call  searches  all 
open  resource  files,  irrespective  of  the  search  sequence  in  effect. 

For  information  on  the  format  and  content  of  resource  file  maps,  see  "Resource  file 
format"  earlier  in  this  chapter. 


♦   Note:  This  call  provides  greater  application  flexibility;  however,  most  applications  will 
not  need  to  issue  this  call. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


filelD 


Stack  after  call 


Long— Space  for  result 

Word— ID  of  resource  file  to  find 

<— SP 


Previous  contents 


-     mapHandle    - 


Errors 


Long— Handle  of  resource  file  map;  NIL  if  none  found 
<— SP 

$1E07        resFiieNotFound  Specified  file  ID  does  not  match 

an  open  file 

extern  pascal  Long  GetMapHandle (filelD) ; 
Word      filelD; 
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filelD  Specifies  the  resource  file  whose  map  is  to  be  returned.  This  value  is 

obtained  from  the  OpenResourceFile  tool  call.  Typically,  your 
program  sets  this  parameter  with  the  file  ID  for  a  particular  resource 
file.  However,  this  field  also  supports  the  following  special  values: 

NIL  returns  handle  to  map  for  current  resource  file 

$FFFF  returns  handle  to  map  for  system  resource  file 
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GetOpenFileRefNum     $1F1E 

Returns  the  GS/OS  file  reference  number  (refNum)  associated  with  the  resource  fork  of 
an  open  resource  file.  Your  program  specifies  the  resource  file  by  means  of  its  file  ID.  The 
Resource  Manager  searches  all  open  resource  files  for  a  file  with  a  matching  ID. 

Your  program  may  use  this  reference  number  to  read  data  from  the  resource  file.  However, 
your  program  should  very  careful  to  maintain  the  structure  of  the  fork  during  write 
operations;  careless  writing  could  destroy  the  resource  fork.  Further,  your  program  should 
never  directly  close  the  file  using  the  reference  number.  Only  the  Resource  Manager  should 
close  files  it  has  opened. 

For  information  on  the  format  and  content  of  resource  file  maps,  see  "Resource  file 
format"  earlier  in  this  chapter. 


♦   Note:  This  call  provides  greater  application  flexibility;  however,  most  applications  will 
not  need  to  issue  this  call. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


filelD 


Word— Space  for  result 
Word— ID  of  resource  file  to  find 
<— SP 


Stack  after  call 


Previous  contents 


openReJNum 


Errors 


$1E07 


Word — GS/OS  file  reference  number 
<— SP 


resFileNotFound 


Specified  file  ID  does  not  match 
an  open  file 


extern  pascal  Word  GetOpenFileRefNum (filelD) ; 
Word      filelD; 
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filelD  Specifies  the  resource  file  whose  reference  number  is  to  be  returned. 

This  value  is  obtained  from  the  openResourceFiie  tool  call. 
Typically,  your  program  sets  this  parameter  with  the  file  ID  for  a 
particular  resource  file.  However,  this  field  also  supports  the  following 
special  values: 

NIL  returns  reference  number  for  current  resource  file 

$FFFF  returns  reference  number  for  system  resource  file 
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GetResourceAttr     $1B1£ 

Returns  the  attribute  flag  word  for  a  specified  resource.  Your  program  specifies  the  type 
and  ID  for  the  desired  resource.  For  more  information  about  the  format  and  content  of 
the  attribute  word,  see  "Resource  attributes"  earlier  in  this  chapter. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


resourcelD 


Stack  after  call 


Word— Space  for  result 
Word— Type  of  resource  to  find 

Long— ID  of  resource  to  find 

<— SP 


Previous  contents 


resourceAttr 


Errors 
C 


$1E06 


Word— Attribute  word  for  specified  resource 
<— SP 


resNotFound 


Specified  resource  not  found 


extern  pascal  Word  GetResourceAttr (resourceType, 
resourcelD) ; 


Word      resourceType; 
Long      resourcelD; 
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GetResourceSize     $1D1E 

Returns  the  size  of  the  specified  resource.  Your  program  specifies  the  type  and  ID  for  the 
desired  resource.  Resource  size  is  defined  as  the  number  of  bytes  the  resource  occupies  in 
the  resource  fork  on  disk. 


Parameters 

Stack  before  call 

Previous  contents 

Space 

Long— Space  for  result 

resourceType 

Word— Type  of  resource  to  find 

resourcelD 

Long— ID  of  resource  to  find 

<— SP 

Stack  after  call 

Previous  contents 

-    resourceSize    - 

Long— Size  of  specified  resource 

<— SP 

Errors                  $1E06 

resNotFound                 Specified  resource  not  found 

C                             exte 

rn  pascal   Long  GetResourceSize (resourceType, 

resourcelD) ; 

Word 

resourceType; 

Long 

resourcelD; 
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HomeResourceFile     $151E 


Returns  the  file  ID  of  the  resource  file  that  contains  a  specified  resource.  Your  program 
specifies  the  type  and  ID  for  the  resource  in  question. 

♦   Note:  If  multiple  resources  share  the  specified  type  and  ID  values,  and  your  program 
has  changed  the  resource  search  sequence  (with  the  setCurResourceFile  tool 
call),  this  call  may  return  a  different  result  than  on  previous  calls. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


resourcelD 


Stack  after  call 


Word— Space  for  result 
Word— Type  of  resource  to  find 

Long— ID  of  resource  to  find 

<— SP 


Previous  contents 


fllelD 


Errors 
C 


$1E06 


Word— File  ID  for  home  resource  file  for  resource;  NIL  if  not  found 
<— SP 
resNotFound  Specified  resource  not  found 


extern  pascal  Word  HomeResourceFile (resourceType, 
resourcelD) ; 

Word      resourceType; 
Long      resourcelD; 
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LoadAbsResource     $271E 

Loads  a  resource  into  a  specified  absolute  memory  location.  Your  program  specifies  the 
type  and  ID  of  the  resource  to  load,  the  memory  location  into  which  the  Resource 
Manager  is  to  load  the  resource,  and  the  maximum  number  of  bytes  to  load.  Note  that  the 
resAbsLoad  flag  in  the  Attributes  word  for  the  desired  resource  must  be  set  to  1. 

♦   Note:  This  call  does  not  respect  the  disk  load  setting  maintained  by  the 
SetResourceLoad  tool  call. 


A  Warning        Most  applications  will  not  have  to  issue  this  call.  In 
order  to  use  this  call  you  must  have  a  thorough 
understanding  of  using  absolute  memory.  Issuing  this 
call  with  an  incorrectly  set  loadAddress  parameter  will 
corrupt  system  memory.  ▲ 


Parameters 

Stack  before  call 


Previous  contents 


Space 


-    loadAddress    - 


maxSize 


resourceType 


resourcelD 


Long— Space  for  result 

Long— Address  at  which  to  load  resource 

Long— Maximum  number  of  bytes  to  load 

Word— Type  of  resource  to  find 

Long— ID  of  resource  to  find 

<— SP 


Stack  after  call 


Previous  contents 


-    resourceSize    - 


Long— Size  of  resource  on  disk 
<— SP 
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Errors 


$1E03 


resNoConverter 


$1E06         resNotFound 
GS/OS  errors 


No  converter  routine  to  load 
resource 

Specified  resource  not  found 

Returned  unchanged 


loadAddress 


extern  pascal  Long  LoadAbsResource (loadAddress, 
maxSize,  resourceType,  resourcelD) ; 

Word      resourceType; 

Long      loadAddress,  maxSize,  resourcelD; 

Specifies  the  memory  location  at  which  the  Resource  Manager  is  to 
load  the  resource.  If  your  program  passes  a  NIL  value,  the  Resource 
Manager  uses  the  address  stored  in  the  resHandie  field  of  the 
appropriate  entry  in  the  resource  index. 
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LoadResource     $0E1E 

Loads  a  resource  into  memory  and  returns  a  handle  to  that  location.  Your  program 
specifies  the  type  and  ID  of  the  resource  to  load.  The  returned  handle  provides 
addressability  to  the  resource. 

The  LoadResource  call  searches  both  memory  and  disk  for  the  specified  resource.  If  the 
resource  is  already  in  memory,  LoadResource  returns  a  handle  to  that  memory  location. 
If  the  resource  has  been  purged  from  memory,  LoadResource  reloads  the  resource  and 
returns  its  handle.  If  the  resource  has  not  been  loaded,  LoadResource  allocates  a  handle, 
loads  the  resource,  and  returns  the  handle  to  your  program. 

Your  program  may  manipulate  the  resource  while  it  is  in  memory,  and  may  even  change  the 
size  of  the  resource  (to  any  size  other  than  zero  bytes).  If  you  want  the  changes  to  be 
reflected  in  the  resource  file,  use  the  MarkResourceChange  tool  call  to  set  on  the 
changed  attribute  for  the  file.  The  Resource  Manager  will  then  write  the  changed  resource 
to  disk  the  next  time  the  resource  file  is  updated.  Your  program  can  force  the  Resource 
Manager  to  write  the  resource  to  disk  immediately  by  issuing  either  the  writeResource 
or  the  UpdateResourceFile  tool  call. 

Note  that  your  program  should  not  dispose  of  the  handle;  only  the  Resource  Manager 
should  free  the  memory  that  it  allocates. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


resource® 


Stack  after  call 

Previous  contents 


-  resourceHandle  - 


Long — Space  for  result 
Word— Type  of  resource  to  find 
Long— ID  of  resource  to  find 
<— SP 


Long— Handle  of  resource  in  memory 
<— SP 
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Errors 


$1E03 


resNoConverter 


$1E06         resNotFound 
GS/OS  errors 
Memory  Manager  errors 


No  converter  routine  to  load 

resource 

Specified  resource  not  found 

Returned  unchanged 

Returned  unchanged 


extern  pascal   Long  LoadResource (resourceType, 
resourcelD) ; 

Word  resourceType; 

Long  resourcelD; 
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MarkResourceChange     $101E 

Instructs  the  Resource  Manager  to  write  the  specified  resource  to  disk  the  next  time  its 
resource  file  is  updated.  Your  program  specifies  the  type  and  ID  of  the  resource  to  be 
marked  as  changed. 

Use  this  call  when  you  want  in-memory  changes  to  a  resource  to  be  permanent. 

Parameters 

Stack  before  call 


Previous  contents 


changeFlag 


resourceType 


resourcelD 


Stack  after  call 


Word— BOOLEAN;  TRUE  for  changed,  FALSE  for  not  changed 
Word— Type  of  resource  to  find 

Long— ID  of  resource  to  find 

<— SP 


Previous  contents 


Errors 
C 


$1E06 


<— SP 
resNotFound 


Specified  resource  not  found 


extern  pascal  void  MarkResourceChange (changeFlag, 
resourceType,  resourcelD) ; 

Word      changeFlag,  resourceType; 
Long      resourcelD; 
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MatchResourceHandle     $1E1E 

Returns  the  type  and  ID  of  a  resource,  given  a  handle  to  that  resource.  The  Resource 
Manager  searches  all  open  resource  files  for  a  match,  without  regard  for  the  search 
sequence  in  effect. 


Note:  The  Resource  Manager  has  been  optimized  to  access  resources  by  type  and  ID, 
irrespective  of  the  number  of  resources  in  the  system.  While 
MatchResourceHandle  works  well  with  relatively  small  numbers  of  resources  (less 
than  100),  for  files  with  large  numbers  of  resources  this  call  can  be  very  slow.  In  order 
to  avoid  this  overhead,  consider  storing  the  resource  type  and  ID  in  the  resource 
structure,  so  that  your  program  can  direcdy  access  this  information. 


Parameters 

Stack  before  call 


Previous  contents 


foundRec 


-  resourceHandle 


Stack  after  call 


Long— Pointer  to  location  in  which  to  return  type  and  ID 

Long— handle  of  resource 
<— SP 


Previous  contents 


Errors 
C 


$1E06 


<— SP 
resNotFound 


Specified  resource  not  found 


extern  pascal  void  MatchResourceHandle (foundRec, 
resourceHandle) ; 

Pointer   foundRec; 

Long      resourceHandle; 
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foundRec  Must  point  to  a  location  in  memory  that  can  accept  6  bytes  of  data: 

the  type  and  ID  of  the  resource  in  question.  On  successful  return  from 
MatchResourceHandie,  that  location  will  contain  the  following 
data: 


$00 
$02 


—    resourceType 


resourcelD 


Word— Type  of  resource 


Long— ID  of  resource 
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OpenResourceFile     $0A1E 

Opens  a  specified  resource  file,  making  it  the  current  file,  and  returns  a  unique  file  ID  to 
the  calling  program.  Your  program  specifies  the  class  1  GS/OS  pathname  to  the  desired 
resource  file.  The  Resource  Manager  loads  the  resource  map  into  memory,  along  with  any 
resources  marked  to  be  pre-loaded  (resPreLoad  flag  is  set  to  1  in  the  Attributes  word 
for  the  resource). 

Parameters 

Stack  before  call 


Previous  contents 


Space 


openAccess 


-     mapAddress 


filename 


Word— Space  for  result 
Word— File  access 

Long— Address  of  resource  map  in  memory 

Long— Pointer  to  GS/OS  class  1  pathname  for  resource  file 
<— SP 


Stack  after  call 


Previous  contents 


filelD 


Word— ID  of  open  resource  file 
<— SP 


Errors 


$1E06          resNotFound 

Specified  resource  not  found 

$1E09         resNoUniquelD 

Too  many  resource  files  open 

$1E0B         resSysIsOpen 

System  resource  file  is  already 

open 

GS/OS  errors 

Returned  unchanged  (EOF  if 

empty  fork) 

Memory  Manager  errors 

Returned  unchanged 

extern  pascal  Word  OpenResourceFile (openAccess, 
mapAddress,  fileName) ; 

Word      openAccess; 

Pointer   mapAddress,  fileName; 
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openAccess  Contains  GS/OS  file  access  privileges  for  the  resource  file.  See  the 

GS/OS  Reference  for  more  information. 

mapAddress  To  open  a  resource  file  on  disk,  set  this  field  to  NIL.  If  the  map  is  in 

memory,  load  this  field  with  a  pointer  to  that  map.  In  this  case,  the 
Resource  Manager  opens  the  file  that  is  already  in  memory. 
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ReleaseResource     $171E 

Sets  the  purge  level  of  the  memory  used  by  a  resource.  Your  program  specifies  the  type 
and  ID  of  the  resource  whose  memory  is  to  be  freed,  and  the  purge  level  to  be  assigned  to 
the  memory.  See  Chapter  12,  "Memory  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for 
more  information  about  purge  levels  and  memory  management.  Note  that  this  call  does 
not  unlock  the  handle. 

Parameters 

Stack  before  call 


Previous  contents 


purgeLevel 


resourceType 


resourcelD 


Stack  after  call 


Previous  contents 


Errors 


Word — Purge  level  for  memory 
Word— Type  of  resource  to  find 

Long— ID  of  resource  to  find 

<— SP 


<— SP 

$1E06    resNotFound 
$1E0C    resHasChanged 


Specified  resource  not  found 
Resource  has  been  changed  but 
not  updated 


C  extern  pascal  void  ReleaseResource (purgeLevel, 

resourceType,  resourcelD) ; 

Word      purgeLevel,  resourceType; 
Long       resourcelD; 

purgeLevel  Specifies  the  Memory  Manager  purge  level  to  be  assigned  to  the  freed 

memory.  Valid  Memory  Manager  purge  levels  lie  in  the  range  of  0  to  3. 
In  order  to  direct  the  Resource  Manager  to  immediately  dispose  of 
the  handle,  set  this  field  to  a  negative  value. 
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RemoveResource     $0F1E 

Deletes  a  resource  from  its  resource  file  and  releases  any  memory  used  by  the  resource. 
Your  program  specifies  the  type  and  ID  of  the  resource  to  be  deleted.  After  successful 
return  from  this  call,  the  specified  resource  is  no  longer  available  for  access  or  loading. 


Parameters 

Stack  before  call 

Previous  contents 

resourceType 

Word— Type  of  resource  to  find 

resourcelD 

Long— ID  of  resource  to  find 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Ern 

are                  $1E0£ 
$1E0I 

1        resNotFound                 Specified  resource  not  found 
i        resDiskFuii                  Volume  full 

extern  pascal  void  RemoveResource (resourceType, 
resourcelD) ; 

Word      resourceType; 
Long      resourcelD; 
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ResourceConverter     $281E 


Installs  or  removes  a  converter  routine  from  either  the  application  or  system  converter  list. 
Your  program  specifies  the  address  of  the  converter  routine,  the  type  of  resource  the 
routine  acts  on,  and  flags  indicating  the  type  of  operation  to  perform  and  the  list  to 
modify.  For  background  information  on  resource  converter  routines,  see  "Resource 
converter  routines"  earlier  in  this  chapter. 

The  Resource  Manager  maintains  two  classes  of  converter  routine  lists:  one  for  your 
application  and  one  for  the  system.  Each  application  has  its  own  converter  routine  list.  All 
programs  share  access  to  the  system  list.  When  the  Resource  Manager  searches  for  a 
routine  to  convert  a  resource  of  a  given  type,  it  first  searches  the  application  list  for  the 
calling  program,  then  the  system  list.  As  a  result,  your  program  can  override  converter 
routines  in  the  system  list  by  installing  a  routine  for  the  same  resource  type  in  its 
application  list.  Applications  must  never  log  routines  into  or  out  of  the  system  converter 
list. 

An  application  can  log  in  up  to  10,922  converter  routines.  Note,  however,  that  the 
Resource  Manager  does  not  check  for  this  limit.  The  same  converter  routine  can  be  logged 
in  for  more  than  one  resource  type. 

The  system  contains  a  standard  routine  to  convert  code  resources.  Use  the 
GetcodeResConverter  Miscellaneous  Tool  Set  tool  call  to  obtain  the  address  of  that 
routine  (see  Chapter  39,  "Miscellaneous  Tool  Set  Update,"  in  this  book  for  details  on  the 
GetcodeResConverter  call). 

Parameters 

Stack  before  call 


Previous  contents 


converter 


resourceType 


logFlags 


Long— Pointer  to  converter  routine 
Word— Type  of  resource  acted  on  by  the  routine 
Word— Flag  governing  action  and  list  to  access 
<— SP 


Stack  after  call 


Previous  contents 


<— SP 
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Errors  $1E0D       resDiff  converter        Another  converter  already  logged 

in  for  this  resource  type 
Memory  Manager  errors  Returned  unchanged 

C  extern  pascal  void  ResourceConverter (converter, 

resourceType,  logFlags) ; 

Pointer   converter; 

Word      resourceType,  logFlags; 

logFlags  Specifies  whether  to  log  the  converter  routine  into  or  out  of  its  list. 

Also  specifies  which  list  (application  or  system)  to  access: 

Reserved  Bits  2-15     Must  be  set  to  0 

list  Bit  1  Indicates  which  routine  list  to  access: 

1  -  System  converter  list 

0  -  Application  converter  list 
action                     Bit  0          Specifies  action  to  take: 

1  -  Log  routine  into  list 

0  -  Log  routine  out  of  list 
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SetCurResourceApp     $131E 

Tells  the  Resource  Manager  that  another  application  will  now  be  issuing  Resource  Manager 
calls.  This  call  is  used  by  desk  accessories  and  application  switchers  (see  "Application 
switchers  and  desk  accessories"  earlier  in  this  chapter  for  more  information).  Before 
issuing  this  call,  your  program  must  have  registered  itself  with  the  Resource  Manager  by 
calling  ResourceStartUp. 

Parameters 

Stack  before  call 


Previous  contents 


userlD 


Stack  after  call 


Word— User  ID  of  application  that  will  be  using  Resource  Manager 
<— SP 


Previous  contents 


Errors 


$1E08 


<— SP 
resBadAppID 


User  ID  unknown  to  Resource 
Manager  (has  not  called 
ResourceStartUp) 


extern  pascal  void  SetCurResourceApp (userlD) ; 
Word      userlD; 
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SetCurResourceFile     $111E 

Makes  a  specified  resource  file  the  current  file.  The  Resource  Manager  searches  typically 
start  with  the  current  resource  file,  so  by  specifying  a  particular  file  as  the  current  file,  your 
program  can  control  the  file  search  sequence.  For  more  information  about  Resource 
Manager  search  processing,  see  "Using  resources"  earlier  in  this  chapter. 

Parameters 

Stack  before  call 


Previous  contents 


filelD 


Stack  after  call 


Word— File  ID  of  resource  file  to  be  made  current  file 
<— SP 


Previous  contents 


Errors 
C 


<— SP 

$1E07        resFiieNotFound  Specified  resource  file  not  found 

extern  pascal   void  SetCurResourceFile (filelD) ; 
Word  filelD; 
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SetResourceAttr     $1C1E 

Sets  the  attributes  for  a  resource.  Your  program  specifies  the  type  and  ID  for  the  desired 
resource  and  a  new  attribute  word  for  the  resource.  The  Resource  Manager  replaces  the 
existing  attribute  word  for  the  resource  with  the  one  provided  to  this  call.  For  more 
information  about  the  format  and  content  of  the  attribute  word,  see  "Resource 
attributes"  earlier  in  this  chapter. 

If  your  program  changes  the  attributes  of  a  resource,  it  should  not  also  mark  the  resource 
as  changed.  The  Resource  Manager  automatically  tracks  these  changes. 

Note  that  these  changes  only  affect  future  use  of  the  resource.  For  example,  if  your 
program  changes  the  attributes  for  a  resource  to  indicate  that  it  should  be  locked  into 
memory  (sets  attrLocked  flag  to  1),  that  action  does  not  change  the  status  of  any 
current  instances  of  that  resource  in  memory.  However,  the  next  time  the  Resource 
Manager  allocates  a  handle  for  the  resource,  the  memory  for  that  new  handle  will  be 
locked. 

Parameters 

Stack  before  call 


Previous  contents 


resourceAttr 


resourceType 


resourcelD 


Stack  after  call 


Word— New  attribute  flag  word  for  resource 
Word— Type  of  resource  to  find 
Long— ID  of  resource  to  find 
<— SP 


Previous  contents 


Errors 
C 


$1E06 


<— SP 

resNotFound 


Specified  resource  not  found 


extern  pascal  void  SetResourceAttr (resourceAttr, 
resourceType,  resourcelD) ; 


Word      resourceAttr,  resourceType; 
Long      resourcelD; 
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SetResourceFileDepth     $251E 

Sets  the  number  of  files  Resource  Manager  is  to  search  during  a  search  operation,  and 
returns  the  previous  search  depth  setting.  For  more  information  about  the  Resource 
Manager's  search  sequence,  see  "Resource  file  search  sequence"  earlier  in  this  chapter. 


Parameters 

Stack  before  call 

Previous  contents 

Space 

Word— Space  for  result 

searchDepth 

Word — Number  of  files  to  search 

<— SP 

Stack  after  call 

Previous  contents 

originalDepth 

Word— Search  file  depth  before  call 

<— SP 

Errors                  None 

C 

exte 

rn  pascal  Word 

Word 


SetResourceFileDepth (searchDepth) ; 


searchDepth; 


searchDepth  Specifies  the  number  of  files  to  search.  SetResourceFileDepth 

accepts  the  following  special  values: 

NIL  Return  current  search  depth  without  changing  it 

$FFFF  Search  all  files 
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SetResourcelD     $1A1E 


Changes  the  ID  for  a  resource  to  a  new  value.  Your  program  specifies  the  type  and  current 
ID  for  the  resource  to  be  changed. 

If  your  program  changes  the  ID  value  for  a  resource,  it  should  not  mark  the  resource  as 
changed.  The  Resource  Manager  automatically  tracks  these  changes. 

Parameters 

Stack  before  call 


Previous  contents 


newID 


resourceType 


currentID 


Stack  after  call 


Previous  contents 


Errors 


$1E05 
$1E06 


Long— New  ID  for  resource 
Word— Type  of  resource  to  find 
Long— Current  ID  of  resource  to  find 
<— SP 


<— SP 
resDupID 

resNotFound 


Specified  new  ID  already 
in  use  for  this  type 
Specified  resource  not  found 


extern  pascal  void  SetResourcelD (newID, 
resourceType,  currentID) ; 

Long      newID,  current  ID; 
Word      resourceType; 
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SetResourceLoad     $24lE 

Controls  Resource  Manager  access  to  disk  when  loading  resources.  If  you  disable  disk 
loading,  the  Resource  Manager  will  not  load  resources  from  disk,  but  will  allocate  empty 
handles  for  requested  resources.  However,  if  a  resource  had  been  loaded  into  memory 
prior  to  disk  loading  being  disabled,  the  Resource  Manager  will  return  a  valid  handle.  For 
example,  a  LoadResource  tool  call  will  return  an  empty  handle  if  loading  is  set  to  FALSE 
and  the  resource  has  not  been  loaded  into  memory  previously. 


Note:  Most  applications  will  not  issue  this  call. 


Parameters 

Stack  before  call 

Previous  contents 

Space 

Word— Space  for  result 

readFlag 

Word— Flag  controlling  Resource  Manager  disk  access 

<— SP 

Stack  after  call 

Previous  contents 

originalFlag 

Word— Flag  setting  prior  to  call 

<— SP 

Errors                  None 

C 

exte 

rn  pascal  Word  SetResourceLoad (readFlag) ; 

readFlag 


Word 


readFlag; 


Specifies  the  new  setting  for  the  read  flag.  This  call  also  supports  a 
special  value  that  just  returns  the  current  flag  setting: 


0 
1 
Negative 


Do  not  read  resources  from  disk 

Read  resources  from  disk,  if  necessary 

Return  current  setting  only— no  change  to  current 

setting 
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originalFlag  Contains  the  previous  flag  setting: 


0  Do  not  read  resources  from  disk 

1  Read  resources  from  disk,  if  necessary 
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UniqueResourcelD     $191E 

Returns  a  unique  resource  ID  for  a  specified  resource  type.  Your  program  specifies  the 
resource  type  for  the  ID,  and  may  optionally  constrain  the  new  ID  to  a  defined  range.  The 
Resource  Manager  allocates  the  new  ID,  guaranteeing  that  it  is  not  used  by  any  of  your 
program's  currently  available  resources. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


IDRange 


resourceType 


Stack  after  call 


Previous  contents 


resourcelD 


Errors 


Long— Space  for  result 

Word— Range  of  ID;  $FFFF  for  any  valid  ID  value 
Word— Type  of  resource 
<— SP 


Long— Unique  resource  ID 
<— SP 


$1E04    resNoCurFile 
$1E09    resNoUniquelD 


There  is  no  current  resource  file 
No  unique  ID  found 


extern  pascal  Long  UniqueResourcelD (IDRange, 
resourceType) ; 


IDRange 


Word 


IDRange,  resourceType; 


Specifies  a  65,535  element  range  within  which  Resource  Manager  is  to 
allocate  the  new  resource  ID.  The  value  of  IDRange  becomes  the  high- 
order  word  of  the  new  ID.  The  Resource  Manager  then  allocates  a 
unique  ID  from  the  65,535  possible  remaining  values. 
UniqueResourcelD  provides  this  facility  so  that  application 
programs  can  manage  logical  groups  of  resources,  differentiated  by  ID 
number  ranges. 
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Resource  IDs  in  the  $07FF  range  are  reserved  for  system  use.  Ranges 
from  $0800  through  $FFFE  are  invalid.  The  following  table  summarizes 
the  valid  values  for  IDRange: 


IDRange 


Lowest  possible  ID  returned 


Highest  possible  ID  returned 


$0000 

$00000001  (ML  is  invalid) 

$0000FFFF 

$0001 

$00010000 

$0001 FFFF 

$0002 

$00020000 

$0002FFFF 

(and  so  on) 

$07FE  $07FE0000  $07FEFFFF 

$07FF  Reserved  for  system  use 

$0800-$FFFE      Invalid  range  values 

$FFFF  $00000001  $07FEFFFF 

(directs  Resource  Manager  to  allocate  from  any  application  range) 
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UpdateResourceFile     $0D1E 

Applies  any  modifications  that  have  been  made  to  resources  in  memory  to  their  resource 
file,  thus  making  those  changes  permanent.  Your  program  specifies  the  file  ID  of  the 
resource  file  to  be  updated.  The  Resource  Manager  then  locates  and  updates  all  resources 
for  that  file.  If  necessary,  UpdateResourceFile  will  write  the  resource  map  to  disk. 

♦   Note:  Most  applications  will  not  issue  this  call  because  the  ResourceShutDown  tool 
call  automatically  updates  all  resources  opened  by  a  program. 


Parameters 

Stack  before  call 


Previous  contents 


filelD 


Stack  after  call 


Word— ID  of  open  resource  file 
<— SP 


Previous  contents 


Errors 


<— SP 
resNoConverter 

resFileNotFound 

resDiskFull 


$1E03 

$1E07 

$1E0E 
GS/OS  errors 

extern  pascal  void  UpdateResourceFile (filelD) ; 
Word      filelD; 


No  converter  routine  found  for 

resource  type 

No  resource  file  found  with 

specified  file  ID 

Volume  full 

Returned  unchanged 
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WriteResource     $l6lE 

Directs  the  Resource  Manager  to  write  a  modified  resource  to  its  resource  file.  Your 
program  specifies  the  type  and  ID  of  the  resource.  If  that  resource  has  been  modified 
(reschanged  flag  set  to  1  in  the  Attributes  flag  word),  the  Resource  Manager  writes  the 
resource  to  its  resource  file  on  disk.  A  resource  is  marked  changed  as  a  result  of 
AddResource,  MarkResourceChange,  or  SetResourceAttr  (with  resChanged 

set  to  1)  tool  calls. 

♦   Note:  Most  applications  will  not  issue  this  call  because  the  ResourceShutDown  and 
cioseResourceFiie  tool  calls  automatically  write  all  changed  resources  to  the 
appropriate  resource  file  (unless  the  resource  is  write-protected). 


Parameters 

Stack  before  call 


Previous  contents 


resourceType 


resourcelD 


Word— Type  of  resource  to  write 
Long— ID  of  resource  to  write 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1E03 


<— SP 

resNoConverter 


$1E06  resNotFound 
$1E0E  resDiskFull 
GS/OS  errors 


No  converter  routine  found  for 
resource  type 
Resource  not  found 
Volume  full 
Returned  unchanged 


extern  pascal  void  WriteResource (resourceType, 
resourcelD) ; 

Word      resourceType; 
Long      resourcelD; 
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Resource  Manager  summary 

This  section  briefly  summarizes  the  constants,  data  structures,  and  error  codes  used  by 
the  Resource  Manager. 


Table  45-1        Resource  Manager  constants 


Name 


Value         Description 


mapFlag  values 

mapChanged  $0002 

resAttr  flag  values 

resChanged  $0020 

resPreLoad  $0040 


resProtected 


resAbsLoad 


resConverter 


resMemAttr 


$0080 


$0400 


$0800 


$C31C 


System  file  ID 

sysFilelD  $0001 


Set  to  1  if  the  map  has  changed  and  must  be  written 
to  disk 


Set  to  1  if  the  resource  has  changed  and  must  be 

written  to  disk 

Set  to  1  if  the  resource  should  be  loaded  into  memory 

by  OpenResourceFile 

Set  to  1  if  the  resource  should  never  be  written  to 

disk 

Set  to  1  if  the  resource  should  be  loaded  at  an 

absolute  memory  location 

Set  to  1  if  the  resource  requires  a  converter  routine 

when  being  loaded  into  memory  or  being  written  to 

disk 

Flags  passed  to  the  NewHandie  Memory  Manager 

tool  call  when  allocating  memory  for  the  resource 

File  ID  of  the  system  resource  file 
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Table  45-2        Resource  Manager  data  structures 


Name 

Offset/Value 

Type 

Description 

ResHeaderRec 

(resource  file  header  record) 

rFileVersion 

$0000 

LongWord 

Format  version  of  resource  fork 

rFileToMap 

$0004 

LongWord 

Offset  from  start  of  fork  to  resource 

map  record 

rFileMapSize 

$0008 

LongWord 

Size,  in  bytes,  of  resource  map 

rFileMemo 

$000C 

128  bytes 

Space  reserved  for  application  use 

rFileRecSize 

$008C 

Size  of  ResHeaderRec 

MapRec  (resource  map  record) 

mapNext 

$0000 

Handle 

Handle  of  next  resource  map  in 
memory 

mapFlag 

$0004 

Word 

Bit  flags 

mapOf fset 

$0006 

LongWord 

Offset  from  start  of  fork  to  resource 
map  record 

mapSize 

$000A 

LongWord 

Size,  in  bytes,  of  resource  map 

mapToIndex 

$000E 

Word 

Offset  from  start  of  map  to 
maplndex 

mapFileNum 

$0010 

Word 

GS/OS  file  reference  number  for  open 
resource  file 

mapID 

$0012 

Word 

Resource  Manager  file  ID  assigned  to 
this  resource  file 

mapIndexSize 

$0014 

LongWord 

Total  number  of  resource  reference 
records  in  maplndex 

mapIndexUsed 

$0018 

LongWord 

Number  of  used  resource  reference 
records 

mapFreeListSize 

$001C 

Word 

Total  number  of  free  block  records  in 
mapFreeList 

mapFreeListUsed 

$001 E 

Word 

Number  of  used  free  block  records 

mapFreeList 

$0020 

n  bytes 

Array  of  free  block  records 
(FreeBlockRec) 

maplndex 

$0020+n 

m  bytes 

Array  of  resource  reference  records 

(ResRefRec) 
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FreeBiockRec  (free  block  record) 

bikoffset  $0000  LongWord 


blkSize 


$0004 


LongWord 


blkRecSize  $0008 

ResRef  Rec  (resource  reference  record) 

resType  $0000  Word 

res  id  $0002  LongWord 

resoffset  $0006  LongWord 


resAttr 

$000A 

Word 

resSize 

$000C 

LongWord 

resHandle 

$0010 

Handle 

resRecSize 

$0014 

Offset,  in  bytes,  to  start  of  this  block 

of  free  space 

Size,  in  bytes,  of  this  block  of  free 

space 

Size  of  FreeBiockRec 

Resource  type 

Resource  ID 

Offset,  in  bytes,  from  start  of  resource 

fork  to  this  resource 

Attribute  bit  flags  for  the  resource 

Size,  in  bytes,  of  the  resource  in  the 

resource  fork 

Handle  of  resource  in  memory 

Size  of  ResRef  Rec 
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Table  45-3        Resource  Manager  error  codes 


Code 


$1E0D 


$1E0E 


Name 


$1E01 

resForkUsed 

$1E02 

resBadFormat 

$1E03 

resNoConverter 

$1E04 

resNoCurFile 

$1E05 

resDupID 

$1E06 

resNotFound 

$1E07 

resFileNotFound 

$1E08 

resBadAppID 

$1E09 

resNoUniquelD 

$1E0A 

resIndexRange 

$1E0B 

resSysIsOpen 

$1E0C 

resHasChanged 

resDiff Converter 


resDiskFull 


Description 


Resource  fork  not  empty 

Resource  fork  not  correctly  formatted 

No  converter  routine  available  for 

resource  type 

There  are  no  open  resource  files 

Specified  resource  ID  is  already  in  use 

Resource  was  not  found 

Resource  file  was  not  found 

User  ID  not  found;  calling  program  has 

not  issued  ResourceStartUp  tool 

all 

No  more  resource  IDs  available 

Index  is  out  of  range 

System  file  is  already  open 

Resource  marked  changed;  specified 

operation  not  allowed 

Different  converter  already  logged  in 

for  this  resource  type 

Volume  full 
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Chapter  46   Scheduler 


There  are  no  changes  in  the  Scheduler.  The  complete  reference  for  the 
Scheduler  is  in  Volume  2,  Chapter  19  of  the  Apple  IIGS  Toolbox  Reference. 
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Chapter  47   Sound  Tool  Set  Update 


This  chapter  documents  new  features  of  the  Sound  Tool  Set.  The 
complete  reference  to  the  Sound  Tool  Set  is  in  Volume  2,  Chapter  21  of 
the  Apple  IIGS  Toolbox  Reference. 

♦   Note:  You  must  read  the  Apple  IIGS  Hardware  Reference  to  understand 
some  of  the  concepts  presented  in  this  chapter. 
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Error  corrections 

This  section  provides  corrections  to  the  documentation  of  the  Sound  Tool  Set  in  the 
Apple  IIGS  Toolbox  Reference. 

m   The  documentation  of  the  FFSoundDoneStatus  call  includes  an  error.  You  will  note 
that  the  paragraph  that  describes  the  call  does  not  agree  with  the  "Stack  after  call" 
diagram.  The  text  states  that  the  call  returns  TRUE  if  the  specified  sound  is  still 
playing,  whereas  the  diagram  states  that  it  returns  FALSE  if  still  playing.  The  diagram, 
not  the  text,  is  correct. 

■   There  is  an  undocumented  distinction  between  a  generator  that  is  playing  a  sound  and 
one  that  is  active.  A  generator  that  is  playing  a  sound  returns  FALSE  in  response  to  an 
FFSoundDoneStatus  call.  One  that  is  active  may  or  may  not  be  playing  a  sound;  the 
value  of  the  flag  returned  by  FFSoundstatus  is  TRUE.  Active  generators  are  those 
that  are  allocated  to  a  voice.  At  any  given  moment  the  generator  may  be  playing  a 
sound,  and  so  the  FFSoundDoneStatus  returns  FALSE— or  it  may  be  silent  between 
notes,  in  which  case  FFSoundDoneStatus  returns  TRUE. 
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Clarification 


This  section  presents  more  complete  information  about  the  FFStartsound  tool  call, 
including  further  explanation  of  its  parameters,  a  new  error  code,  an  example  procedure 
for  moving  a  sound  from  the  Macintosh  to  the  Apple  IIGS  and  some  sample  code 
demonstrating  the  use  of  the  call.  The  original  documentation  for  this  call  is  in 
Chapter  20,  "Sound  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference. 


FFStartSound 

The  freeform  synthsizer  is  designed  to  play  back  long  wave  forms.  In  order  to  handle 
longer  waveforms  the  synthesizer  uses  two  buffers  (which  must  be  the  same  size), 
alternating  its  input  from  one  to  the  other.  When  the  synthesizer  exhausts  a  buffer,  it 
generates  an  interrupt  and  then  starts  reading  data  from  the  other  buffer.  The  Sound  Tool 
Set  services  the  interrupt  and  begins  refilling  the  empty  buffer.  This  process  continues 
until  the  waveform  has  been  completely  played. 

Note  that  all  synthesizer  input  buffers  must  be  buffer-size  aligned.  That  is,  if  you  have 
allocated  4K  buffers,  then  those  buffers  must  be  aligned  on  4K  memory  boundaries. 

Parameter  Block 


$00 

waveStart 

Long 

$04 

waveSize 

Word 

$06 

freqOf fset 

- 

Word 

$08 

docBuf fer 

Word 

$0A 

bufferSize 

Word 

$0C 

nextWavePtr 

Long 

$10 

volSetting 

Word 
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waveStart 


waveSize 


f reqOf f set 


docBuf fer 


buf ferSize 


nextWavePtr 


volSetting 


The  starting  address  of  the  wave  to  be  played,  not  in  DOC  RAM  but  in 
Apple  IIGS  system  RAM.  The  Sound  Tool  Set  loads  the  waveform  data 
into  DOC  RAM  as  it  is  played. 

The  size  in  pages  of  the  wave  to  be  played.  A  value  of  1  indicates  that 
the  wave  is  one  page  (256  bytes)  in  size;  a  value  of  2  indicates  that  it 
is  two  pages  (512  bytes)  in  size— and  so  on  as  you  might  expect.  The 
only  anomaly  is  that  a  value  of  0  specifies  that  the  wave  is  65,536 
pages  in  size. 

This  parameter  is  copied  directiy  into  the  Frequency  High  and 
Frequency  Low  registers  of  the  DOC.  See  the  previous  discussion  of 
those  registers  for  more  complete  information. 

Contains  the  address  in  Sound  RAM  where  buffers  are  to  be  allocated. 
This  value  is  written  to  the  DOC  WaveForm  Jable  Pointer  register.  The 
low-order  byte  is  not  used,  and  should  always  be  set  to  0. 

The  lowest  three  bits  set  the  values  for  the  table-size  and  resolution 
portions  of  the  DOC  Bank-Select/Table-size/Resolution  register.  See 
the  previous  discussion  of  that  register  for  details. 

This  is  the  address  of  the  next  waveform  to  be  played.  If  the  field's 
value  is  0,  then  the  current  waveform  is  the  last  waveform  to  be 
played. 

The  low  byte  of  the  volSetting  field  is  copied  directly  into  the 
Volume  register  of  the  DOC.  All  possible  byte  values  are  valid. 


New  error  code 


$0817        iRONotAssignedErr      No  master  IRQ  was  assigned. 
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Moving  a  sound  from  the  Macintosh  to  the  Apple  IIGS 

To  move  a  digitized  sound  from  the  Macintosh  to  the  Apple  IIGS  and  play  the  sound,  you 
will  have  to  perform  the  following  steps 

1 .  Save  the  sound  as  a  pure  data  file  on  the  Macintosh. 

2.  Transfer  the  file  to  the  Apple  IIGS  (using  Apple  File  Exchange,  for  example). 

3.  Filter  all  the  zero  sample  bytes  out  of  the  file  by  replacing  them  with  bytes  set  to  $01. 
This  is  very  important,  because  the  Apple  IIGS  interprets  zero  bytes  as  the  end  of  a 
sample. 

4.  Load  the  sound  into  memory  with  GS/OS  calls. 

5.  Play  the  sound  with  the  FFStartsound  tool  call. 

Set  the  f  reqof  f  set  parameter  to  $01B7  in  order  to  play  the  sound  at  the  same 
tempo  as  the  Macintosh. 


Sample  code 

This  assembly-language  code  sample  demonstrates  the  use  of  the  FFStartsound  tool 
call. 


PushWord    chanGenType 
PushLong    #STParamBlk 
FFStartsound 


;  set  generator  for  FFSynth 
;  address  of  parm  block 
;  start  free-from  synth 


ChanGenType  DC.W  $0201 


generator  2,  FFSynth 


STParamBlk   DS.L  1 


Entry 

WaveSize 

WaveSize 

DS.W  1 

Freq 

DC.W  $200 

Start 

DC.W  $8000 

Size 

DC.W  $6 

Nxtwave 

DC.L  $0 

Vol 

DC.W  $FF 

store  the  address  of  the 
sound  in  system  memory  here 

store  the  number  of  pages  to 

play  here 
A9  set  for  each  sample  once 
start  at  beginning 
16k  buffers 
no  new  param  block 
maximum  volume 
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New  information 

This  section  provides  new  information  about  the  Sound  Tool  Set. 

■  The  four  sound  and  music  tools,  that  is,  the  Note  Sequencer,  Note  Synthesizer,  MIDI 
Tool  Set,  and  Sound  Tool  Set,  work  together  and  must  have  compatible  versions.  The 
current  required  versions  are; 

Sound  Tool  Set  version  2.4 

Note  Synthesizer  version  1.3 

Note  Sequencer  version  1.3 

MIDI  Tool  Set  version  1.2 

■  The  Sound  Tool  Set  soundBootmit  call  has  been  changed  to  initialize  the 
MidiinitPoii  vector  ($E101B2)  to  an  rtl. 

■  The  setuserSoundiRQv  tool  call  allows  you  to  establish  a  custom  synthesizer 
interrupt  handler.  In  addition  to  the  description  in  the  Toolbox  Reference,  note  that 
your  interrupt  handler  should  verify  that  it  should  handle  the  interrupt  by  checking  the 
synthesizer  mode  value,  which  is  passed  as  an  input  parameter  to  the  interrupt  handler 
in  the  accumulator  register. 

If  your  routine  does  not  process  the  interrupt,  it  should  make  a  jmp  to  the  next  routine 
in  the  interrupt  chain,  taking  care  to  preserve  the  state  of  the  accumulator.  If  your 
routine  does  process  the  interrupt,  it  should  set  the  carry  flag  to  0  and  return  via  an  rtl 
instruction. 
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Introduction  to  sound  on  the  Apple  IIGS 

This  section  provides  some  general  background  on  the  various  sound-related  tool  sets 
available  on  the  Apple  IIGS.  There  are  five  sound  tool  sets:  the  Sound  Tool  Set,  the  Note 
Sequencer,  the  Note  Synthesizer,  the  MIDI  Tool  Set,  and  the  Audio  Compression  and 
Expansion  (ACE)  Tool  set.  Although  each  provides  distinct  functionality,  they  can 
complement  one  another  and  generate  fairly  sophisticated  sound  applications. 

■  The  Sound  Tool  Set  will  play  back  a  digitized  sample  of  any  length  and  at  any 
frequency.  Note  that  the  sample  must  fit  into  system  memory. 

■  The  Note  Synthesizer  also  plays  digitized  samples,  but  with  much  greater  control  over 
the  sample,  including  the  ability  to  loop  within  the  sample  and  control  the  sound 
envelope,  but  is  limited  to  sounds  smaller  than  65,536  bytes. 

■  The  MIDI  Tool  Set  allows  you  to  send  and  receive  MIDI  data. 

■  The  Note  Sequencer  combines  the  functionality  of  the  Note  Synthesizer  and  MIDI 
Tool  Set,  allowing  you  to  send  MIDI  data  and  drive  the  Note  Synthesizer 
simultaneously. 

■  The  Audio  Compression  and  Expansion  Tool  Set  provides  dramatic  reduction  in 
sound  disk-storage  requirements,  with  only  slight  degradation 'in  sound  quality. 

By  combining  the  facilities  offered  by  these  tools,  you  can  easily  build  impressive  sound 
applications.  For  example,  you  could  develop  a  program  that  reads  MIDI  data  into  the 
Note  Synthesizer  while  also  saving  that  data  to  disk  for  later  input  to  the  Note  Sequencer. 
This  program  would  turn  the  Apple  IIGS  into  a  MIDI  sound  source  with  the  capability  to 
save  its  songs  for  later  playback. 
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Note  Sequencer 

The  DOC  interrupts  that  drive  the  Note  Synthesizer  also  drive  the  Note  Sequencer.  Before 
the  Note  Synthesizer  handles  an  interrupt,  it  passes  it  to  the  Note  Sequencer  and  allows 
other  interrupt  handlers  access  to  it  before  taking  control.  The  Note  Sequencer  checks  its 
increment  value  against  its  clock  value  to  determine  whether  to  take  any  action.  If  enough 
time  has  passed,  it  checks  for  delay;  if  a  delay  is  specified,  it  checks  to  determine 
whether  it  has  waited  long  enough  to  satisfy  the  delay  requirement.  If  it  hasn't,  it  simply 
returns.  If  it  has  waited  long  enough,  then  it  checks  all  playing  notes  with  specified 
durations  to  determine  whether  it  is  time  to  turn  them  off.  If  so,  it  turns  those  notes  off. 
It  then  parses  the  next  seqltem  in  the  current  sequence  and  makes  Note  Synthesizer  and 
MIDI  Tool  Set  calls  to  execute  it.  If  the  chord  bit  is  set  in  the  current  seqltem,  it 
immediately  fetches  the  next  seqltem  for  execution.  If  the  delay  bit  is  set,  then  it 
calculates  the  required  delay  and  sets  the  delay  flag.  It  then  returns. 


Note  Synthesizer 

One  DOC  oscillator  drives  the  Note  Synthesizer  and  the  Note  Sequencer,  using  the 
interrupts  that  it  generates  at  the  end  of  waveforms,  or  at  0  values  in  the  waveform.  The 
Sound  Tool  Set  services  such  interrupts,  then  passes  them  to  the  Note  Synthesizer  for 
further  handling  if  it  is  needed.  Because  the  Sound  Tool  Set  and  the  Note  Synthesizer  use 
the  same  direct-page  space,  it  is  appropriate  to  use  the  Note  Synthesizer  to  assign 
oscillators  for  your  own  purposes  even  if  you  don't  use  the  Note  Synthesizer  any  further 
with  the  assigned  oscillators. 

The  Note  Synthesizer's  operation  requires  considerable  processing.  If  processor  time  is  in 
short  supply  and  you  want  to  use  the  Note  Synthesizer  to  produce  sounds,  use  envelopes 
that  are  simple  and  do  not  use  vibrato,  and  use  low  updateRate  values.  See 
Chapter  41,  "Note  Synthesizer,"  in  this  book  for  further  information. 

The  Note  Synthesizer  and  Note  Sequencer  run  at  interrupt  time,  and  current  versions  are 
fully  compatible  with  the  MIDI  Tool  Set. 
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Sound  General  Logic  Unit  (GLU) 

One  quirk  of  the  sound  general  logic  unit  (GLU)  is  that  the  value  for  volume  in  the  control 
register  is  a  write-only  value.  It  is  possible,  however,  to  maintain  the  system  volume 
specified  by  the  Control  Panel  setting  and  still  write  to  the  GLU.  To  find  the  system 
volume  setting,  use  the  Miscellaneous  Tool  Set's  GetAddr  call  to  find  the  address  of 
irq  .  volume  and  use  the  value  stored  at  that  address. 


Vocabulary 

This  section  describes  a  number  of  terms  that  have  special  meanings  in  the  context  of  the 
Apple  IIGS  Digital  Oscillator  Chip  (DOC). 

Oscillator 

There  are  32  oscillators  on  the  DOC.  They  are  not  true  oscillators  in  the  ordinary  sense  of 
a  circuit  that  generates  a  waveform.  Rather,  they  are  circuits  that  take  as  input  a 
waveform  stored  as  digital  data,  and  output  an  audio  signal  based  on  those  data. 

Generator 

Each  generator  used  by  the  Sound  Tool  Set  is  actually  a  pair  of  DOC  oscillators,  usually 
operating  in  swap  mode  when  used  by  the  Sound  Tool  Set.  In  swap  mode  the  two 
oscillators  alternate  playing  and  halting,  with  each  oscillator  playing  while  the  other  is 
halted.  When  one  oscillator  reaches  the  end  of  its  current  waveform,  it  stops  playing  and 
the  other  oscillator  takes  over,  until  it  reaches  the  end  of  its  waveform  and  the  first 
oscillator  takes  over  again. 


Voice 

A  single  audio  signal  that  can  be  independently  controlled.  A  synthesizer  that  can  play 
eight  notes  at  one  time  is  normally  said  to  have  eight  voices. 
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Sample  rate 

A  waveform  is  stored  in  the  Apple  IIGS  computer's  memory  as  some  number  of  digital 
samples  of  a  sound.  The  number  of  samples  that  the  Apple  IIGS  plays  each  second  is 
referred  to  as  the  sample  rate.  The  sample  rate  of  the  DOC  is  fixed  by  the  number  of 
oscillators  that  are  enabled,  that  is,  by  the  value  of  register  $E1  on  the  DOC.  The  sample 
rate  depends  only  upon  this  value;  changing  other  parameters  does  not  affect  sample  rate. 


(0+2) 


where 

S  is  the  sample  rate 

C  is  the  input  clock  rate,  which  is  always  7.159  MHz 

O  is  the  number  of  oscillators  enabled  (32  is  standard) 

The  default  sample  rate,  with  all  32  oscillators  enabled,  is  about  26.31985  kHz;  that  is  to 
say,  the  Apple  IIGS,  operating  at  its  default  sample  rate,  plays  about  26,320  samples  per 
second.  It  is  possible  to  generate  higher  sampling  rates  by  reducing  the  number  of  enabled 
oscillators.  However,  the  low-pass  filter  on  the  Apple  IIGS  is  a  5-pole  Chebyshev  active 
filter  with  a  roll-off  at  10  KHz.  Consequently,  higher  sampling  rates  may  not  result  in  higher 
perceived  sound  quality. 

Drop  sample  tuning 

The  DOC  plays  waveforms  by  looking  up  wave  data  in  a  table  in  memory  and  sweeping 
through  a  stored  waveform.  This  strategy  has  the  advantage  that  it  can  produce  very 
faithful  reproductions  of  digitally  sampled  sound.  If,  however,  you  want  the  DOC  to  play 
a  waveform  at  a  pitch  different  from  that  at  which  it  was  recorded,  it  cannot  simply 
generate  it  at  a  different  frequency  as  a  true  voltage-controlled  oscillator  can.  Instead,  the 
DOC  changes  the  pitch  by  using  a  method  called  drop  sample  tuning.  To  raise  the  pitch 
of  a  sample  one  octave,  the  DOC  doubles  its  frequency  by  skipping  every  other  sample  in 
the  sequence.  Similarly,  to  lower  the  pitch  one  octave,  it  cuts  the  frequency  in  half  by 
playing  each  sample  in  the  sequence  twice. 

The  disadvantage  of  drop  sample  tuning  is  that  at  higher  frequencies,  some  of  the  samples 
are  dropped,  or  lost,  and  changing  the  pitch  also  changes  the  duration  of  each  waveform. 
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Frequency 

Frequency  refers  both  to  the  output  frequency  of  the  audio  signal  generated  by  the  DOC 
and  to  the  value  of  the  DOC  frequency  register.  We  normally  mean  the  value  of  the 
rrequency  register,  which  determines  but  is  not  equal  to,  the  output  frequency.  Frequency 
direcdy  determines  the  perceived  pitch  of  a  sound;  higher  frequencies  are  higher  pitches. 

Sound  RAM 

The  DOC  has  64  KB  of  random-access  memory  dedicated  to  storage  of  sound  samples. 
This  RAM,  which  contains  the  sampled  waveforms  the  DOC  plays,  is  referred  to  as 
Sound  RAM. 


Waveform 

A  waveform  consists  of  data  representing  the  stored  form  of  a  digitally  sampled  audio 
signal. 

DOC  registers 

There  are  ten  different  registers  in  the  DOC.  There  is  a  set  of  registers  for  each  of  the  DOC 
oscillators.  That  is,  each  of  the  first  seven  registers  has  32  different  values,  one  for  each 
DOC  oscillator.  The  registers  are  Frequency  Low,  Frequency  High,  Volume,  Waveform 
Data  Sample,  Waveform  Table  Pointer,  Control,  Bank  Select/Table-Size/Resolution, 
Oscillator  Interrupt,  Oscillator  Enable,  and  A/D  Converter. 
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Frequency  registers 

Two  8-bit  frequency  registers,  Frequency  Low  and  Frequency  High,  are  paired  to  produce 
a  single  16-bit  frequency  value.  The  output  frequency  of  a  sample  an  be  represented  by 


0  V2(17+Ry 


•FHL 


where 

O  is  the  output  frequency  in  hertz,  assuming  that  one  cycle  of  the  sound 

exactly  fills  the  table  size 
S  is  the  sample  rate  (26.32  KHz) 

R  is  the  resolution  value  in  the  Bank-Select/Table-Size/Resolution  register; 

valid  values  lie  in  the  range  from  0  through  7 
FHL      is  the  combined  values  of  Frequency  Low  and  Frequency  High;  valid 

values  lie  in  the  range  from  0  through  65,535 

This  calculation  assumes  that  the  wave  table  contains  exactly  one  cycle  of  the  waveform. 
The  resolution  and  the  table  size  are  3-bit  values,  and  this  calculation  assumes  they  are 
equal. 

If  one  cycle  of  the  sound  does  not  exactly  fill  the  table  size,  then  you  can  use  the  following 
formula  to  calculate  the  output  frequency: 


/Fi\     /  S'FHL  \ 
VSRi/  A  20+R-™V 


where 

O  is  the  output  frequency  in  hertz 

Fi         is  the  frequency  of  the  sampled  waveform  in  hertz 

SRi        rate  at  which  you  sampled  the  original  sound  (in  samples  per  second) 

S  is  the  Apple  IIGS  sample  rate  (26.32  KHz) 

FHL      is  the  combined  values  of  Frequency  Low  and  Frequency  High;  valid 

values  lie  in  the  range  from  0  through  65,535 
R  is  the  resolution  value  in  the  Bank-Select/Table-Size/Resolution  register; 

valid  values  lie  in  the  range  from  0  through  7 
TAB      Table-size  value  in  the  Bank-select/Table-size/Resolution  register;  valid 

values  lie  in  the  range  from  0  through  7 
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Volume  register 

The  value  in  the  Volume  register  directly  controls  the  volume  of  the  sound  output  for  that 
oscillator. 

Waveform  Data  Sample  register 

This  is  a  read-only  register  that  always  contains  the  value  of  the  sample  that  an  oscillator  is 
currently  playing. 

Waveform  Table  Pointer  register 

This  register  is  also  referred  to  as  the  Address  Pointer  register.  It  identifies  which  page  of 
Sound  RAM  contains  the  start  of  the  current  sample.  The  ff  start  sound  parameter 
docBuffer  is  written  directly  to  this  register. 

Control  register 

The  Control  register  establishes  several  attributes  of  its  associated  oscillator.  These 
attributes  include  the  oscillator's  mode,  whether  the  oscillator  is  halted,  whether  it  will 
generate  an  interrupt  at  the  end  of  its  cycle,  and  the  channel  to  which  the  oscillator  is 
assigned. 

■    Interrupt  enable  bit  Bit  3  of  the  Control  register  is  the  interrupt  enable  bit.  When  this 
bit  is  set  to  1,  the  oscillator  generates  an  interrupt  when  it  reaches  the  end  of  a 
waveform  or  plays  a  sample  with  a  value  of  0. 

Unless  you  have  issued  the  setsoundMiRQv  tool  call  to  set  a  custom  interrupt  vector 
(see  Chapter  20,  "Sound  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference  for  more 
information),  the  Sound  Tool  Set  fields  these  interrupts  first.  Upon  entry  to  the 
interrupt  routine,  the  accumulator  register  contains  the  low-order  nibble  of  the 
genNumFFSynth  parameter  from  the  FFStartSound  tool  call  that  assigned  the 
oscillator.  If  the  value  of  this  nibble  indicates  that  the  interrupt  is  for  the  Sound  Tool 
Set,  the  interrupt  handler  processes  the  interrupt.  Otherwise,  it  passes  the  interrupt  on 
to  other  interrupt  routines  (see  the  discussion  of  the  setuserSoundiRQv  tool  call  in 
Chapter  20,  "Sound  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference  for  information  on 
setting  vectors  to  user  interrupt  routines). 
•   Mode  The  mode  value  consists  of  two  bits,  MO  and  Ml.  There  are  thus  four  possible 
modes,  which  are  designated  as  free-run  mode  or  loop  mode  (00),  one-shot  mode  (01), 
sync/AM  mode  (10),  and  swap  mode  (11). 
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In  free-run  or  loop  mode,  the  oscillator  sweeps  through  a  waveform  to  the  end,  playing 
the  values  it  encounters,  then  starts  again  at  the  beginning  of  the  waveform  and 
generates  an  interrupt  if  the  interrupt  enable  bit  is  set  to  1.  The  generator  also 
interrupts  if  it  encounters  a  0,  or  if  it  reaches  the  end  of  the  waveform. 

In  one-shot  mode,  the  oscillator  sweeps  through  its  waveform  to  the  first  0  value  or  to 
the  end,  generates  an  interrupt  if  the  interrupt  enable  bit  is  setto  1,  and  halts. 

In  swap  mode,  an  oscillator  sweeps  through  its  waveform  to  the  first  0  value,  or  to  the 
end  of  the  waveform,  generates  an  interrupt,  and  halts,  turning  control  over  to  a 
partner  oscillator.  Only  one  halt  bit  an  be  set  to  1  at  any  given  time  for  a  pair  of 
oscillators  in  swap  mode;  setting  the  halt  bit  of  one  oscillator  to  1  forces  the  other's  to 
0. 

Generators  always  consist  of  an  even/odd  pair  of  oscillators— for  example,  oscillators 
0  and  1  form  a  generator,  as  do  oscillators  2  and  3,  and  so  on.  The  Note  Synthesizer 
normally  uses  each  pair  with  the  even-numbered  oscillator  in  swap  mode  and  the  odd- 
numbered  oscillator  in  loop  mode.  The  Sound  Tool  Set  normally  uses  both  oscillators 
of  a  pair  in  swap  mode. 

Channel  register 

The  Channel  register  specifies  a  sound's  stereo  position.  Currently,  only  the  low-order  bit  is 
significant.  A  value  of  0  in  this  bit  sets  the  oscillator's  stereo  position  to  the  right  channel; 
a  value  of  1  sets  it  to  the  left  channel. 

Bank-Select/Table-Size/Resolution  register 

This  register  sets  the  table  size  for  stored  waveforms,  the  resolution  of  the  waveform,  and 
the  bank  selection  for  the  oscillator.  When  it  plays  a  sound,  the  DOC  adds  the  value  of  the 
Frequency  register  to  its  accumulator.  It  multiplexes  the  resulting  value  with  the  address 
pointer  to  determine  the  address  in  DOC  RAM  of  the  sample  to  play.  The  table  size 
determines  how  many  bits  of  the  Address  Pointer  register  are  accessible  to  the  DOC  for 
this  operation;  a  larger  table  size  reduces  the  number  of  Address  Pointer  register  bits  used 
in  the  address  calculation,  and  reduces  the  precision  with  which  a  particular  sample  can  be 
located.  If  eight  bits  of  the  Address  Pointer  register  are  used  to  locate  the  next  sample, 
the  DOC  can  distinguish  twice  as  many  starting  points  as  it  can  if  only  seven  bits  are  used. 

Each  time  the  DOC  cycles  it  adds  the  contents  of  the  Frequency  register  to  its  24-bit 
accumulator.  It  then  appends  a  subrange  of  the  accumulator's  24  bits  to  the  value  of  the 
address  pointer  and  uses  the  resulting  value  as  an  absolute  address  in  DOC  RAM.  It  then 
plays  the  sample  stored  at  that  location. 

The  resolution  value,  which  is  the  lowest  three  bits  of  the 

Bank-Select/Table-Size/Resolution  register,  determines  the  lowest  bit  of  the  accumulator 
value  that  will  be  appended  to  the  address  pointer. 
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The  table-size  value,  which  is  the  next  three  bits  above  the  resolution,  determines  both 
width  of  the  address  pointer  value  and  the  width  of  the  accumulator  value.  The  width  of 
each  value  is  the  number  of  bits  the  DOC  uses  from  that  register.  For  example,  the  DOC 
accumulator  is  a  24-bit  register,  but  the  DOC  uses  only  eight  of  those  bits  when  the  table 
size  is  256  bytes. 

The  DOC  uses  only  part  of  each  register,  the  accumulator  and  the  address  pointer,  to 
determine  the  place  in  memory  that  it  will  play  next.  For  any  table  size  greater  than  256 
bytes  (1  page),  it  overwrites  the  lowest  bits  of  the  address  pointer  with  bits  from  the 
accumulator.  Figure  47-1  shows  the  correspondence  between  table  size,  resolution,  and 
the  portions  of  the  Address  Pointer  register  and  accumulator  used  to  determine  the 
location  of  the  next  sample  to  be  played. 


Figure  47-1      DOC  registers 
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The  resolution  acts  as  an  offset  value,  determining  which  bit  is  the  lowest  accumulator  bit 
to  be  appended  to  the  Address  Pointer  register.  The  effect  of  these  computations  is  that 
if  you  increase  the  resolution  by  1,  the  pitch  of  the  waveform  will  be  one  octave  lower.  If 
you  increase  the  resolution  value  by  2,  the  pitch  will  be  four  octaves  lower— and  so  on  in 
powers  of  two. 

The  table-size  value  is  a  3-bit  value  that  is  equal  to  the  resolution  value  in  calls  to 
FFStartSound.  It  specifies  the  size  of  the  DOC  RAM  partitions  used  to  contain 
waveforms  that  are  to  be  played.  The  correspondence  between  table-size  values  and  the 
table  sizes  is 

RAM  buffer  size 

1  page  (256  bytes) 

2  page  612  bytes) 
4  pages  (1024  bytes) 
8  pages  (2048  bytes) 
16  pages  (4096  bytes) 
32  pages  (8192  bytes) 
64  pages  (16,384  bytes) 
128  pages  (32,768  bytes)- 

Both  the  table-size  and  resolution  values  are  copied  into  their  respective  bits  in  the 
Bank-Select/Table-Size/Resolution  register  from  the  lowest  three  bits  of  the  buffersize 
parameter  to  the  FFStartSound  call. 

•   Bank-select  bit  The  bank-select  bit  is  bit  6.  It  is  reserved  for  the  use  of  Apple 
Computer,  Inc.  and  should  always  be  0. 

Oscillator  Interrupt  register 

This  register  contains  a  bit  that  specifies  whether  an  interrupt  has  occurred  and,  if  so, 
contains  the  number  of  the  oscillator  that  generated  the  interrupt.  The  oscillator  number 
(0-3D  is  stored  in  bits  1  through  5  of  this  register. 

Oscillator  Enable  register 

|The  Oscillator  Enable  register  specifies  the  number  of  enabled  oscillators  (0-3D. 

A/D  Converter  register 

This  register  always  contains  the  current  sample  from  the  analog-to-digital  converter  built 
into  the  Digital  Oscillator  Chip. 
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MIDI  and  interrupts 

The  MIDI  Tool  Set  automatically  recovers  incoming  MIDI  data,  but  to  do  so  it  requires 
that  interrupts  never  be  disabled  for  longer  than  290  microseconds.  If  an  application 
disables  interrupts  for  longer  than  this,  it  should  call  the  MidiinputPoii  vector  at  least 
every  270  microseconds  to  ensure  that  the  data  are  properly  received  and  the  input  buffer 
is  cleared.  When  MIDI  input  is  not  enabled,  the  vector  is  still  serviced,  but  at  minimal  cost 
in  CPU  cycles.  Under  these  circumstances,  the  call  to  the  vector  sacrifices  only  two 
instructions,  namely  a  jsl  and  an  rtl. 

Normally  one  CPU  cycle  on  the  Apple  IIGS  lasts  about  1  microsecond,  but  it  may  take 
slighdy  longer  if  it  accesses  soft  switches  or  slow  memory. 
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New  Sound  Tool  Set  calls 

There  are  four  new  tool  calls  that  provide  greater  flexibility  when  playing  free-form 
sounds.  The  FFSetupSound  and  FFStartPiaying  alls  allow  you  to  schedule  a  sound 
for  playback  at  a  later  time.  setDOCReg  and  ReadDOCReg  provide  easy  access  to  the 
DOC  registers. 


FFSetupSound     $1508 

This  call  is  identical  to  the  FFStartSound  tool  call,  but  does  not  actually  start  playing 
the  specified  sound.  Use  the  FFStartPiaying  tool  call  to  start  playing.  This  call  gives 
you  the  option  of  setting  up  a  sound  and  playing  it  later. 

Parameters 

Stack  before  call 


Previous  contents 


channelGen 


-  paramBlockPtr  - 


Word— Channel,  generator  type  word 

Long— Pointer  to  FFStartSound  parameter  block 

<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


channelGen 


None 


<— SP 


extern  pascal  void  FFSetupSound (channelGen, 
paramBlockPtr) ; 


Word 
Pointer 


channelGen; 
paramBlockPtr; 


For  complete  information  on  the  channelGen  parameter,  refer  to  the 

description  of  the  FFStartSound  tool  call  in 

Chapter  20,  "Sound  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference. 
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paramBlockPtr      For  complete  information  on  the  parameter  block  pointed  to  by  the 
paramBlockPtr  parameter,  see  "FFStartsound"  earlier  in  this 
chapter. 
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FFStartPlaying     $1608 

Starts  playing  the  sound  specified  by  the  FFSetupSound  tool  call  on  a  specified  set  of 
generators.  Your  program  passes  a  parameter  to  this  call  indicating  which  generators  are  to 
play  the  sound. 

Parameters 

Stack  before  call 


Previous  contents 


genWord 


Stack  after  call 


Word— Flag  word  indicating  which  generators  to  start 
<— SP 


Previous  contents 


Errors 
C 

genWord 


None 


<— SP 


extern  pascal  void  FFStartPlaying (genWord) ; 


Word 


genWord; 


Specifies  which  generators  to  start.  Each  bit  in  the  word  corresponds 
to  a  generator.  Setting  a  bit  to  1  indicates  that  the  matching  generator 
is  to  play  the  sound.  For  example,  a  genWord  value  of  $4071 
(%0100  0000  0111  0001)  would  start  generators  0,  4,  5,  6,  and  14. 


Warning       A  value  of  $0000  for  this  parameter  is  illegal  and  will 
cause  the  system  to  hang.  ▲ 
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ReadDOCReg    $1808 

Reads  the  DOC  registers  for  a  generator's  oscillator  and  stores  the  register  contents  in  a 
special  format  in  the  target  memory  location.  Your  program  specifies  the  generator  and 
which  oscillator,  as  well  as  the  destination  for  the  register  information.  The  format  of  the 
resultant  data  structure  corresponds  to  the  input  to  the  SetDOCReg  tool  call. 


▲  Warning       This  is  a  very  low-level  call.  You  should  not  use  it  unless 
you  have  a  thorough  understanding  of  the  DOC.  This 
call  may  not  be  supported  in  future  versions  of  the 
system  hardware.  ▲ 


Stack  before  call 

Previous  contents 

-dRegParmBlkPtr  - 

Long— Pointer  to  DOC  register  parameter  block 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C                               extern 

pa 

seal  void  ReadDOCReg (dRegParmBlkPtr) 

Poin 

ter 

dRegParmBlkPtr; 
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dRegParmBlkPtr    Refers  to  a  location  in  memory  to  be  loaded  with  the  contents  of  the 
DOC  registers  for  the  specified  generator. 


$00 

—    oscGenType 

- 

$02 

freqLowl 

$03 

freqHighl 

$04 

voll 

$05 

tablePtrl 

$06 

controll 

$07 

tableSizel 

$08 

freqLow2 

$09 

freqHigh2 

$0A 

vol2 

$0B 

tablePtr2 

$0C 

control2 

$0D 

tableSize2 

-   Word— (see  below) 

Byte— Frequency  Low  register  for  first  oscillator 

Byte— Frequency  High  register  for  first  oscillator 

Byte— Volume  register  for  first  oscillator 

Byte— Waveform  Table  Pointer  register  for  first  oscillator 

Byte— Control  register  for  first  oscillator 

Byte— Table-size  register  for  first  oscillator 

Byte— Frequency  Low  register  for  second  oscillator 

Byte— Frequency  High  register  for  second  oscillator 

Byte— Volume  register  for  second  oscillator 

Byte— Waveform  Table  Pointer  register  for  second  oscillator 

Byte— Control  register  for  second  oscillator 

Byte— Table-size  register  for  second  oscillator 


oscGenType  Bits  8  through  11  specify  the  generator  number  ($0  through  $F) 

whose  registers  are  to  be  retrieved. 


bit  15 


bit  14 


bits  12-13 
bits  8-11 

bits  4-7 
bits  0-3 


Determines  whether  to  get  DOC  registers  for  the  first 

oscillator. 

1  -  Get  the  registers 

0  -  Do  not  get  the  registers 

Determines  whether  to  get  DOC  registers  for  the  second 
oscillator. 

1  -  Get  the  registers 

0  -  Do  not  get  the  registers 

Reserved;  must  be  set  to  0. 

Specify  the  generator  number  for  the  operation.  Valid 

values  lie  in  the  range  from  $0  through  $F. 

Reserved;  must  be  set  to  0. 

Specify  who  is  using  the  generator  (this  value  is 

returned) 
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SetDOCReg     $1708 

Sets  the  DOC  registers  for  a  generator's  oscillator  from  register  contents  stored  in  a  special 
format.  Your  program  specifies  the  generator,  the  oscillator(s)  and  the  register 
information.  The  format  of  the  input  data  structure  corresponds  to  the  output  from  the 
ReadDOCReg  tool  call. 


▲  Warning       This  is  a  very  low-level  call.  You  should  not  use  it  unless 
you  have  a  thorough  understanding  of  the  DOC.  This 
call  may  not  be  supported  in  future  versions  of  the 
system  hardware.  ▲ 


Parameters 

Stack  before  call 


Previous  contents 


-dRegParmBlkPtr  ■ 


Stack  after  call 


Long— Pointer  to  DOC  register  parameter  block 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SetDOCReg (dRegParmBlkPtr) ; 
Pointer   dRegParmBlkPtr; 
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dRegParmBlkPtr    Refers  to  a  location  in  memory  containing  the  new  contents  of  the 
DOC  registers  for  the  specified  generator: 


$00 

—     oscGenType 

- 

$02 

freqLowl 

$03 

freqHighl 

$04 

voll 

$05 

tablePtrl 

$06 

control 1 

$07 

tableSizel 

$08 

freqLow2 

$09 

freqHigh2 

$0A 

vol2 

$0B 

tablePtr2 

$0C 

control2 

$0D 

tableSize2 

-|  Word— {see  below) 

Byte— Frequency  Low  register  for  first  oscillator 

Byte— Frequency  High  register  for  first  oscillator 

Byte— Volume  register  for  first  oscillator 

Byte— Waveform  Table  Pointer  register  for  first  oscillator 

Byte— Control  register  for  first  oscillator 

Byte— Table-size  register  for  first  oscillator 

Byte— Frequency  Low  register  for  second  oscillator 

Byte— Frequency  High  register  for  second  oscillator 

Byte— Volume  register  for  second  oscillator 

Byte— Waveform  Table  Pointer  register  for  second  oscillator 

Byte— Control  register  for  second  oscillator 

Byte— Table-size  register  for  second  oscillator 


oscGenType  Specifies  the  generator  whose  oscillators  are  to  be  written,  along  with 

other  generator  control  block  (GCB)  information  (see 
Chapter  41,  "Note  Synthesizer,"  in  this  book  for  detailed  information 
on  the  format  and  content  of  the  GCB): 


bit  15 


bit  14 


bits  12-13 
bits  8-11 

bits  4-7 
bits  0-3 


Determines  whether  to  set  DOC  registers  for  the  first 

oscillator. 

1  -  Set  the  registers 

0  -  Do  not  set  the  registers 

Determines  whether  to  set  DOC  registers  for  the  second 
oscillator. 

1  -  Set  the  registers 

0  -  Do  not  set  the  registers 

Reserved;  must  be  set  to  0. 

Specify  the  generator  number  for  the  operation.  Valid 

values  lie  in  the  range  from  $0  through  $F. 

Reserved;  must  be  set  to  0. 

Specify  who  is  using  the  generator. 

$0  -  Invalid  value 

$1  -  Free-form  synthesizer 

$2  -  Note  Synthesizer 

$3  -  Reserved 

$4  -  MIDI 

$5-$7  -  Reserved 

$8-$F  -  User-defined 
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Chapter  48   Standard  File  Operations  Tool  Set 


This  chapter  documents  new  features  of  the  Standard  File  Operations 
Tool  Set.  The  complete  reference  to  this  tool  set  is  in  Volume  2, 
Chapter  22  of  the  Apple  IIGS  Toolbox  Reference. 
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New  features  in  the  Standard  File  Operations  Tool  Set 

This  section  explains  new  features  of  the  Standard  File  OperationsTool  Set. 

■  The  Standard  File  Operations  Tool  Set  now  uses  Class  1  calls  to  fully  support  GS/OS.  As 
a  result,  new  tool  set  calls  accept  full  GS/OS  filenames  and  pathnames: 

d   A  total  of  13,107  files,  with  a  total  of  up  to  64  KB  of  name  strings,  can  reside  in  a 
single  folder. 

□   A  filename  can  now  contain  up  to  253  characters. 

a   A  pathname  can  now  contain  up  to  508  characters. 

New  applications  should  use  the  new  tool  set  calls  to  gain  access  to  this  functionality. 

♦   Note:  Since  old  The  Standard  File  Operations  Tool  Set  calls  use  the  new,  longer 
filenames  and  pathnames  internally,  it  is  possible  for  an  old-style  Get  or  Put  call  to 
access  an  AppleShare®  file  with  a  name  that  is  more  than  15  characters  long.  In  this 
case,  the  system  truncates  the  filename  in  the  reply  record.  If  necessary,  the  pathname 
is  also  truncated.  Note,  however,  that  if  the  pathname  will  fit  in  the  reply  record,  then 
it  is  returned  intact,  regardless  of  the  length  of  the  filename  portion  of  the  path.  As  a 
result,  this  representation  of  the  filename  may  exceed  15  characters.  While  this  allows 
the  application  to  open  the  file,  programs  that  cannot  accept  a  filename  with  more 
than  15  characters  may  not  function  predictably. 

■  The  Standard  File  Operations  Tool  Set  now  uses  the  List  Manager  for  some  internal 
functions,  freeing  up  memory  for  application  use. 

The  Standard  File  Operations  Tool  Set  now  requires  that  there  be  four  pages  available 
on  the  application  stack  (three  for  List  Manager,  one  for  the  Standard  File  Operations 
Tool  Set  itself). 

The  new  tool  calls  use  prefixes  differendy.  These  calls  first  check  prefix  8  for  a  valid 
path.  If  prefix  8  is  valid,  the  routines  use  that  path.  If  not,  they  check  prefix  0.  If 
prefix  0  is  valid,  the  routines  copy  it  to  prefix  8,  then  use  it.  If  prefix  0  is  also  invalid, 
the  search  continues  to  the  next  volume. 

Anytime  the  user  changes  the  pathname,  even  during  a  cancelled  Standard  File  dialog, 
the  new  path  is  placed  in  prefix  8.  In  addition,  this  current  path  is  placed  into  prefix  0, 
if  it  fits.  If  the  path  will  not  fit,  prefix  0  is  left  unchanged  and  contains  the  last 
legitimate  pathname  entered. 

Internally,  both  old  and  new  Standard  File  calls  use  prefix  8,  allowing  up  to  508 
characters  in  the  pathname.  However,  the  Standard  File  Operations  Tool  Set  will 
display  a  warning  if,  as  a  result  of  an  old  call,  a  pathname  longer  than  64  characters  will 
be  created. 
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The  Standard  File  Operations  Tool  Set  now  scans  AppleShare  volumes  every  eight 
seconds  for  changes.  The  system  automatically  updates  the  displayed  file  list. 

The  Standard  File  Operations  Tool  Set  now  returns  error  codes.  For  many  internal 
errors,  the  Standard  File  Operations  Tool  Set  will  display  a  detailed  information  dialog 
and  allow  the  user  to  cancel  the  operation. 

When  displaying  a  complete  path,  the  system  now  uses  the  separator  character  found 
in  either  prefix  8  or  0.  Previously,  the  separator  was  always  /,  but  now  typically  will  be 
a  colon  ( : ). 

The  system  now  disables  the  Save  and  NewFolder  buttons  in  Put  dialogs  referencing 
write-protected  volumes.  In  addition,  the  system  will  now  display  a  lock  icon  for  such 
volumes. 

The  Standard  File  Operations  Tool  Set  now  supports  multiple  file  Get  calls.  See  "New 
Standard  File  calls"  later  in  this  chapter  for  call  syntax  details. 

Multifile  dialogs  include  a  new  Accept  button  in  addition  to  the  Open  button.  These 
buttons  operate  as  follows: 

a   When  the  user  has  selected  a  single  file,  both  the  Open  and  Accept  buttons  are 
enabled.  If  the  selected  file  is  not  a  folder,  clicking  either  button  will  return  the 
filename.  If  the  file  is  a  folder,  clicking  Open  lists  the  folder  contents,  while 
clicking  Accept  returns  the  folder  name  to  the  calling  program.  Double-clicking  on  a 
file  works  the  same  as  Accept;  double-clicking  on  a  folder  works  the  same  as  Open. 

d   When  the  user  has  selected  multiple  files,  the  Open  button  is  disabled.  The  user 
must  press  the  Accept  button  to  return  the  filenames  to  the  calling  application.  In 
this  case,  the  returned  file  list  may  contain  both  folder  and  file  names.  Double- 
clicking  is  not  allowed  when  multiple  files  have  been  selected. 

The  Standard  File  Operations  Tool  Set  now  uses  static  text  items  in  its  dialog 
templates.  The  system  will  automatically  change  custom  dialog  templates  to  use  static 
text,  rather  than  user  items.  In  addition,  the  system  now  uses  a  custom  draw  routine 
for  the  path  entry  item.  The  system  automatically  changes  input  dialog  templates  to 
call  the  Standard  File  Operations  Tool  Set's  custom  draw  routine,  unless  the  input 
template  already  references  a  custom  routine,  in  which  case  that  reference  is  not 
changed. 

Your  application  can  now  provide  custom  draw  routines  for  items  in  displayed  file 
lists.  The  Standard  File  Operations  Tool  Set  takes  care  of  dimming  and  selecting  the 
item. 
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m   Standard  File  dialogs  support  the  following  keystroke  equivalents: 

Key  Button  Equivalent 


Esc 

Close 

Command-Up  Arrow 

Close 

Tab 

Volume 

Command-period 

Cancel 

Command-o 

Open 

Command-0 

Open 

Command-Down  Arrow 

Open 

Command-n 

New  Folder 

Command-N 

New  Folder 

New  filter  procedure  entry  interface 

Many  Standard  File  calls  allow  you  to  specify  a  custom  filter  procedure.  These  custom 
routines  can  perform  specific  checking  of  items  for  file  list  inclusion,  beyond  that 
performed  by  the  system.  To  learn  more  about  Standard  File  filter  procedures,  see 
Chapter  22,  "Standard  File  Operations  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference. 

The  new  Standard  File  calls  support  a  different  filter  procedure  entry  interface.  Previously, 
Standard  File  filter  procedures  received  a  pointer  to  a  file  directory  entry  (defined  in  the 
Toolbox  Reference).  New  Standard  File  calls  pass  a  pointer  to  a  GetDirEntry  record, 
which  corresponds  to  the  formatted  output  of  the  GS/OS  GetDirEntry  call.  For  the 
format  and  content  of  the  GetDirEntry  record,  refer  to  Volume  1  of  the  GS/OS 
Reference. 

The  exit  interface  from  these  filter  procedures  has  not  changed.  Your  program  must 
remove  this  pointer  from  the  stack  and  return  a  response  word  indicating  how  the  current 
file  is  to  be  displayed  in  the  file  list. 


Value 

Name 

Description 

0 

1 

2 

noDisplay 
noSelect 

displaySelect 

Do  not  display  file 

Display  the  file,  but  do  not  allow  the  user  to 

select  it 

Display  the  file  and  allow  the  user  to  select  it 
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Custom  item  drawing  routines 

Some  new  Standard  File  calls  allow  you  to  specify  custom  item-drawing  routines.  These 
routines  give  you  the  opportunity  to  create  highly  customized  displays  of  items  in  file 
lists.  The  Standard  File  Operations  Tool  Set  handles  item  dimming  and  selecting. 

On  entry  to  the  custom  item  drawing  routine,  Standard  File  formats  the  stack  as  follows: 

Previous  contents 

Long— Pointer  to  the  member  rectangle 

Long— Pointer  to  the  member  record 

Long— Handle  to  the  list  control 

Block— Reserved  data  for  Standard  File— 24  bytes 

Long— Pointer  to  item  draw  record 

Block— rtl  address— 3  bytes 
<— SP 


-    memRectPtr    - 


memberPtr    — 


controlHndl    - 


Reserved 


-    itemDrawPtr   - 


returnAddr 


The  itemDrawPtr  field  contains  a  pointer  to  a  record  formatted  as  follows: 


$00 

count 

Byte— Length  of  nameString,  in 

$01 

nameString 

Array—  count  bytes  of  file  name 

count*  1 

—              fileType             — 

Word— File  type 

count  +  3 

—          fileAuxType          — 

Long— Auxiliary  file  type 

The  routine  must  remove  this  pointer  from  the  stack  before  returning  to  the  Standard  File 
Operations  Tool  Set.  The  custom  item  drawing  routine  should  not  change  any  of  the  other 
information  on  the  stack. 
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The  custom  drawing  routine  must  draw  both  the  filename  string  and  any  associated  icon. 
The  Standard  File  Operations  Tool  Set  assumes  that  the  standard  system  font  and 
character  size  are  used  for  all  list  items;  changing  either  font  or  character  size  is  not 
recommended.  Note  that  any  icons  must  also  comply  with  these  restrictions  (current 
icons  are  eight  lines  high). 


Standard  File  data  structures 

The  new  Standard  File  tool  calls  accept  and  return  new  style  reply  records  and  type  lists. 
The  formats  for  these  records  follow. 

Reply  record 

Figure  48-1  defines  the  layout  for  the  new-style  Standard  File  reply  record.  You  pass  this 
record  to  many  of  the  new  tool  calls.  Those  calls,  in  turn,  update  the  record  and  return  it  to 
your  program. 


Figure  48-1      New-style  reply  record 


$00 

good 

Word 

$02 

type 

- 

Word 

$04 

_ 

auxType 

- 

Long 

~ 

$08 

nameRefDesc 

- 

Word 

$0A 

_ 

nameRef 

- 

Long 

— 

$0E 

pathRefDesc 

- 

Word 

$10 

_ 

pathRef 

- 

Long 

_ 
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good 

type 

auxType 

nameRefDesc 

$0000 
$0001 
$0003 


nameRef 


pathRefDesc 

$0000 
$0001 
$0003 


pathRef 


Boolean  indicating  the  status  of  the  request.  TRUE  indicates  that  the 
user  opened  the  file;  FALSE  indicates  that  the  user  cancelled  the 
request. 

Contains  the  GS/OS  file  type  information. 

Contains  the  GS/OS  auxiliary  type  information. 

Defines  the  type  of  reference  stored  in  nameRef  (your  program  must 
set  this  field): 

Reference  in  nameRef  is  a  pointer  to  a  GS/OS  class  1  output 

string. 

Reference  in  nameRef  is  a  handle  to  a  GS/OS  class  1  output 

string. 

Reference  in  nameRef  is  undefined.  The  system  will  allocate  a 

new  handle,  correctly  sized  for  the  resulting  GS/OS  class  1  output 

string,  and  return  that  handle  in  nameRef.  This  is  the 

recommended  option. 

On  input,  may  contain  a  reference  to  the  output  buffer  for  the 
filename  string,  depending  upon  the  contents  of  nameRefDesc.  On 
output,  contains  a  reference  to  the  filename  string.  The  reference  type 
is  defined  by  the  contents  of  nameRefDesc.  If  your  program  set 
nameRefDesc  to  $0003,  then  your  program  must  release  the  resulting 
handle  when  it  is  done  with  the  returned  data. 

Defines  the  type  of  reference  stored  in  pathRef  (your  program  must  set 
this  field): 

Reference  in  pathRef  is  a  pointer  to  a  GS/OS  class  1  output 

string. 

Reference  in  pathRef  is  a  handle  to  a  GS/OS  class  1  output 

string. 

Reference  in  pathRef  is  undefined.  The  system  will  allocate  a 

new  handle,  correctly  sized  for  the  resulting  GS/OS  class  1  output 

string,  and  return  that  handle  in  pathRef.  This  is  the 

recommended  option. 

On  input,  may  contain  a  reference  to  the  output  buffer  for  the  file 
pathname  string,  depending  upon  the  contents  of  pathRefDesc.  On 
output,  contains  a  reference  to  the  pathname  string.  The  reference 
type  is  defined  by  the  contents  of  pathRefDesc.  If  your  program 
set  pathRefDesc  to  $0003,  then  your  program  must  release  the 
resulting  handle  when  it  is  done  with  the  returned  data. 
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Multifile  reply  record 

Figure  48-2  defines  the  format  of  the  Standard  File  multifile  reply  record.  The  system 
returns  this  record  format  in  response  to  multifile  Get  requests. 


■    Figure  48-2      Multifile  reply  record 


-    Word 


good 


namesHandle 


Contains  either  the  number  of  files  selected,  or  FALSE  if  the  user 
cancelled  the  request. 

Handle  to  the  returned  data  record.  Your  program  must  dispose  of 
this  handle  when  it  is  done  with  the  returned  data.  The  returned  data 
record  is  formatted  as  follows: 


$00  _    bufferLength   — |  Word 
$02 


fileEntryArray 


Array 


bufferLength    Contains  the  total  length,  in  bytes,  of  the  returned  data  record, 
including  the  length  of  bufferLength. 
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f  ileEntryArray 


An  array  of  file  entries,  each  formatted  as  follows: 


$00 

—      fileType      — 

Won 

$02 

—    auxFileType    — 

Long 

$06 

nameLength 

Byte 

$07 

prefixl 

Byte 

$08 

prefix2 

Byte 

$09 

name 

Arra; 

fileType 

auxFileType 

nameLength 

prefixl 

prefix2 

name 


Contains  the  GS/OS  file  type. 

Contains  the  GS/OS  auxiliary  type. 

Contains  the  length  of  the  following  filename,  including 
the  volume  prefix  bytes  (prefixl  and  pref ix2). 

Volume  prefix  for  the  pathname,  first  byte.  Always  set 
to  8. 

Volume  prefix  for  the  pathname,  second  byte.  Always 
set  to  :. 

Filename  string,  containing  (nameLength  -  2)  bytes  of 
data,  not  to  exceed  253  characters. 


File  type  list  record 

Figure  48-3  shows  the  layout  of  the  Standard  File  type  list  record.  You  use  this  record  with 
Standard  File  calls  that  require  a  file  type  list  as  input  (such  as  SFGetFiie2). 
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Figure  48-3      File  type  list  record 


$00 
$02 


entryCount 


Word 

entryArray  •   Array 


entryCount  Contains  the  number  of  items  in  entryArray. 

entryArray        Array  of  file  type  entries,  each  formatted  as  follows: 


$00 

flags 

Word 

$02 

fileType 

Word 

$04 

_ 

auxFileType 

Long 
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flags 


Defines  how  the  system  is  to  use  f  ileType  and  auxFiieType 
when  selecting  files  to  be  displayed: 


bit  15 


bit  14 


bit  13 


bits  12-0 


Controls  whether  Standard  File  cares  about 

auxiliary  types: 

l  -  Match  any  auxFiieType  value 

0  -  Match  only  the  specified  auxFiieType 
value 

Controls  whether  Standard  File  cares  about  file 
types: 

1  -  Match  any  f  ileType 

0  -  Match  only  the  specified  f  ileType  value 

Disable  selection: 

1  -  Any  files  matching  criteria  specified  in  bits 
14  and  15  will  be  displayed  but  will  not  be 
selectable  (will  be  greyed  out).  Note  that  the 
file(s)  will  not  be  passed  to  the  filter  procedure 
for  the  tool  call. 

Reserved;  must  be  set  to  0. 


♦   Note:  The  settings  of  bits  14  and  15  are  independent.  By  setting  both  bits  to  1,  The 
Standard  File  Operations  Tool  Set  will  match  all  files. 


fileType 


auxFiieType 


Specifies  a  GS/OS  file  type  value  to  match,  according  to  the 
settings  of  the  flags  bits.  If  bit  15  of  flags  is  set  to  0,  then 
this  field  is  ignored. 

Specifies  a  GS/OS  auxiliary  type  value  to  match,  according  to 
the  settings  of  the  flags  bits.  If  bit  14  of  flags  is  set  to  0, 
then  this  field  is  ignored. 
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Standard  File  dialog  templates 

The  Standard  File  Operations  Tool  Set  allows  you  to  define  custom  dialog  boxes  for  the 
Open  File  and  Save  File  dialog  boxes.  To  use  a  custom  dialog  box,  your  program  must 
provide  a  pointer  to  a  dialog  template  to  the  appropriate  Standard  File  routines 
(sFPPutFiie2,  SFPGetFiie2,  or  SFPMuitiFiie2).  The  Standard  File  Operations 
Tool  Set  passes  the  dialog  template  to  the  Dialog  Manager  (GetNewModaiDiaiog  call) 
when  it  establishes  the  user  dialog. 

While  the  latest  version  of  the  Standard  File  Operations  Tool  Set  uses  some  of  the 
template  fields  differently,  old  templates  should  still  work.  The  system  internally  modifies 
old-style  input  templates  to  make  them  compatible  with  current  usage.  New  usage  differs 
in  the  following  ways: 

■  The  boundary  rectangle  for  a  file  list  is  taken  from  the  Files  item  in  each  dialog 
template  and  copied  to  the  List  Manager  record.  The  number  of  files  to  be  displayed  is 
derived  from  the  rectangle  coordinates  by  subtracting  2  from  the  height  and  dividing 
the  result  by  10.  To  avoid  displaying  partial  filenames,  you  should  set  the  rectangle 
height  using  the  same  formula;  that  is,  height=((num_files  *  10)  +  2). 

■  The  Scroll  item  is  no  longer  used  for  single-file  requests.  However,  it  has  been  retained 
in  the  record  for  compatibility  with  old  templates.  For  multifile  Get  requests,  the  new 
tool  calls  define  the  Accept  button  in  the  space  previously  used  by  the  Scroll  item. 

■  Standard  File  calls  copy  the  input  dialog  template  header  to  memory  and  then  update 
it.  Note  that,  for  single-file  Get  calls,  items  5  and  7  are  not  copied  (for  multifile  Get 
calls,  item  5  is  copied).  Similarly,  items  6  and  8  are  not  copied  for  Put  calls. 

The  following  code  examples  contain  the  templates  for  the  standard  Open  File  and  Save 
File  dialog  boxes.  All  these  templates  depend  upon  the  following  string  definitions: 


SaveStr 

str 

'Save1 

OpenStr 

str 

1  Open ' 

CloseStr 

Str 

'Close' 

DriveStr 

str 

'Volume' 

CancelStr 

str 

'Cancel' 

FolderStr 

str 

'New  Folder' 

AcceptStr 

str 

'Accept' 

KbFreeStr 

str 

'~0  free  of 

PPromptStr 

dc.b 

'Save  which  file: 

PEndBuf 

dc.b 

0 

GPromptStr 

dc.b 

'Load  which  file: 

GEndBuf 

dc.b 

0 

"1  k. '       /Dialog  Manager  routine 
;  replaces  *0  &  "1  with  real 
;  values  from  the  disk. 
i 

;end-of -string  byte 


;end-of -string  byte 
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Open  File  dialog  box  templates 

The  Open  File  dialog  box  must  contain  the  following  items  in  this  exact  order: 


Item 


Item  type 


Item  ID 


Open  button       buttonltem  1 

Close  button        buttonltem  2 

Next  button        buttonltem  3 

Cancel  button    buttonltem  4 

Scrollbar              userltem+itemDisable  5 

Path                    userltem  6 

Files                      userltem+itemDisable  7 

Prompt                userltem  8 

♦   Note:  The  Scroll  bar  item  (item  5)  is  not  used  for  single-file  calls.  For  multifile  calls,  this 
item  contains  the  Accept  button  definition. 


♦   Note:  The  Files  item  (item  7)  contains  the  boundary  rectangle  for  the  List  Manager, 
and  serves  no  other  purpose. 

First,  the  templates  for  640  mode: 

GetDialog64  0 


dew 

0,0,114,400 

recommended  drect   of   dialog 
(64  0   mode) 

dew 

-1 

dew 

0,0 

reserved  words 

del 

OpenBut640 

item  1 

del 

CloseBut640 

item  2 • 

del 

NextBut64  0 

item  3 

del 

CancelBut640 

item  4 

del 

Scroll640 

dummy   item  or  ACCEPT  button 

del 

Path640 

item  6 

del 

Files640 

item  7 

del 

Prompt 640 

item  8 

del 

0 
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OpenBut640 

dew 

1 

; item  # 

dew 

61,265,73,375 

; drect 

dew 

Buttonltem 

;type  of  item 

del 

OpenStr 

; Item  descriptor 

dew 

0,0 

/Item  value  &  bit 

flags 

del 

0 

/color  table  ptr 

(nil  is 

default) 

CloseBut640 

dew 

2 

; item  # 

dew 

79,265,91,375 

; drect 

dew 

Buttonltem 

/type  of  item 

del 

CloseStr 

/Item  descriptor 

dew 

0,0 

; Item  value  &  bit 

flags 

del 

0 

/color  table  ptr 

(nil  is 

default) 

NextBut640 

dew 

3 

; item  # 

dew 

25,265,37,375 

/drect 

dew 

Buttonltem 

/type  of  item 

del 

DriveStr 

/ Item  descriptor 

dew 

0,0 

; Item  value  &  bit 

flags 

del 

0 

/color  table  ptr 

(nil  is 

default) 

CancelBut640 

dew 

4 

; item  # 

dew 

97,265,109, 

375 

/ drect 

dew 

Buttonltem 

/type  of  item 

del 

CancelStr 

; Item  descriptor 

dew 

0,0 

/ Item  value  &  bit 

flags 

del 

0 

/color  table  ptr 

(nil  is 

default) 
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Scroll640 

SPECIAL  NOTE:  Scroll  items  are  no  longer  used  by  the  new  calls,  since 
the  List  Manager  takes  care  of  all  scroll  "stuff".  In  single-file 
Get  calls  (also  any  OLD  call) ,  this  item  is  simply  ignored  and  its 
pointer  is  left  out  of  the  header  when  copied  to  RAM.  However,  in 
Multi-Get  calls,  this  item  IS  used  for  the  Accept  button.  The 
following  is  the  recommended  content  for  the  Accept  button: 


dew 

5 

;item  #    (DUMMY   or  ACCEPT   button) 

dew 

43,26f 

>,55,375 

; drect 

dew 

Buttonltem 

;  type 

del 

AcceptStr 

; Item  descriptor 

dew 

0,0 

;Item  value   and  bit   flags 

del 

0 

/color  table 

Path640 

dew 

6 

; item  # 

dew 

12,15, 

24,395 

; drect 

dew 

Userltem 

;  type 

del 

PathDraw 

;Item  descriptor    (user   app. 

specific) 

dew 

0,0 

; Item  value   and  bit   flags 

del 

0 

/color  table 

Files640 

dew 

7 

/ item  # 

dew 

25,18, 

107,215 

/Boundary   rect   for   List   Manager 

dew 

Userltem+ItemDisable 

/  type 

del 

0 

/Item  descriptor 

dew 

0,0 

/ Item  value   and  bit   flags 

del 

0 

/color  table 

Prompt 640 

dew 

8 

/ item  # 

dew 

03,15, 

12,395 

/ drect 

dew 

StatText+ItemDisable 

;  type 

del 

0 

/Item  descriptor    (Text   passed) 

dew 

0 

/size   of   text 

dew 

0 

/Bit   flags 

del 

0 

/color  table 
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Now,  the  templates  for  320  mode: 

GetDialog320 


dew 

0,0,114,260 

dew 

-1 

dew 

0,0 

del 

OpenBut320 

del 

CloseBut320 

del 

NextBut320 

del 

CancelBut320 

del 

Scroll320 

del 

Path320 

del 

Files320 

del 

Prompt 320 

del 

0 

OpenBut320 

dew 

1 

dew 

53,160,65,255 

dew 

Buttonltem 

del 

OpenStr 

dew 

0,0 

del 

0 

CloseBut320 

dew 

2 

dew 

71,160,83,255 

dew 

Buttonltem 

del 

CloseStr 

dew 

0,0 

del 

0 

NextBut320 

dew 

3 

dew 

27,160,39,255 

dew 

Buttonltem 

del 

DriveStr 

dew 

0,0 

del 

0 

drect  of  dialog  (320  mode) 

reserved  word 

item  1 

item  2 

item  3 

item  4 

dummy  item  or  ACCEPT  button 

item  6 

item  7 

item  8 


; item  # 

; drect 

;type  of  item 

; Item  descriptor 

; Item  value  &  bit  flags 

/color  table  ptr  (nil  is  default) 


;item  # 

; drect 

;type  of  item 

/Item  descriptor 

/Item  value  &  bit  flags 

/color  table  ptr  (nil  is  default) 


/item  # 

/ drect 

/ type  of  item 

/Item  descriptor 

/ Item  value  &  bit  flags 

/color  table  ptr  (nil  is  default) 
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CancelBut320 

dew 

4 

; item  # 

dew 

97,160,109, 

255 

; drect 

dew 

Buttonltem 

;type   of  item 

del 

CancelStr 

/Item  descriptor 

dew 

0,0 

; Item  value   &   bit   flags 

del 

0 

; color  table  ptr    (nil   is   default) 

Scroll320 

SPECIAL  NOTE:  Scroll  items  are  no  longer  used  by  the  new  calls,  since 
the  List  Manager  takes  care  of  all  scroll  "stuff".  In  single-file 
Get  calls  (also  any  OLD  call) ,  this  item  is  simply  ignored  and  its 
pointer  is  left  out  of  the  header  when  copied  to  RAM.  However,  in 
Multi-Get  calls,  this  item  IS  used  for  the  Accept  button.  The 
following  is  the  recommended  content  for  the  Accept  button: 


;item  #  (see  SPECIAL  NOTE) 

; drect 

;  type 

; Item  descriptor 

/Item  value  and  bit  flags 

/ color  table 


; item  # 

/ drect 

;  type 

/ Item  descriptor 

/Item  value  and  bit  flags 

/ color  table 


; item  # 

/Boundary  rect  for  list  manager 

;  type 

/Item  descriptor 

/Item  value  and  bit  flags 

/color  table 


dew 

5 

dew 

118,160,130,255 

dew 

Buttonltem 

del 

AcceptStr 

dew 

0,0 

del 

0 

Path320 

dew 

6 

dew 

14,06,26,256 

dew 

Userltem 

del 

PathDraw 

dew 

0,0 

del 

0 

Files320 

dew 

7 

dew 

27,05,109,140 

dew 

Userltem+ItemDisable 

del 

0 

dew 

0,0 

del 

0 
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Prompt320 

dew 

8 

; item  # 

dew 

03,05,12,255 

; drect 

dew 

StatText+ItemDisable 

;  type 

del 

0 

; Item  descriptor 

(Text  passed) 

dew 

0 

;size  of  string 

dew 

0 

;Bit  flags 

del 

0 

/color  table  (0  = 

;  default) 
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Save  File  dialog  box  templates 

The  Save  File  dialog  box  must  contain  the  following  items  in  this  exact  order: 

Item                       Item  type  Item  ID 

Save  button        buttonltem  1 

Open  button       buttonltem  2 

Close  button       buttonltem  3 

Next  button        buttonltem  4 

Cancel  button    buttonltem  5 

Scrollbar             userltem+itemDisable  6 

Path                     userltem  7 

Files                     userltem+itemDisable  8 

Prompt                userltem  9 

Filename           edititem  10 

Free  space         statText  11 

Create  button    buttonltem  12 

♦   Note:  The  Scroll  bar  item  (item  6)  is  not  used  for  single-file  calls. 


♦   Note:  The  Files  item  (item  8)  contains  the  boundary  rectangle  for  the  List  Manager, 
and  serves  no  other  purpose. 
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First,  the  templates  for  640  mode: 

PutDialog640 


dew     0,0,120,320 


recommended  drect  of  dialog 
(640  mode) 


dew 

-1 

dew 

0,0 

■  reserved  word 

del 

SaveButP640 

•  item  1 

del 

OpenButP640 

item  2 

del 

CloseButP640 

■  item  3 

del 

NextButP640 

item  4 

del 

CancelButP640 

item  5 

del 

ScrollP640 

DUMMY  item 

del 

PathP640 

item  7 

del 

FilesP640 

contains  boundary  rect 

only 

del 

PromptP640 

item  9 

del 

EditP640 

item  10 

del 

StatTextP640 

item  11 

del 

CreateButP640 

item  12 

del 

0 

SaveButP640 

dew 

1 

item  # 

dew 

87,204,99,310 

drect 

dew 

Buttonltem           , 

type  of  item 

del 

SaveStr               , 

Item  descriptor 

dew 

0,0 

Item  value  &  bit  flags 

del 

0 

color  table  ptr  (nil  is 

default) 

OpenButP640 

dew 

2 

item  # 

dew 

49,204,61,310 

drect 

dew 

Buttonltem           , 

type  of  item 

del 

OpenStr              , 

Item  descriptor 

dew 

0,0 

Item  value  &  bit  flags 

del 

0 

color  table  ptr  (nil  is 

default) 
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CloseButP640 

dew 

3 

; item  # 

dew 

64,204,76,310 

; drect 

dew 

Buttonltem 

; type   of   item 

del 

CloseStr 

/Item  descriptor 

dew 

0,0 

; Item  value   &   bit   flags 

del 

0 

; color  table  ptr    (nil   is 

default) 

NextButP640 

dew 

4 

; item  # 

dew 

15,204,27,310 

; drect 

dew 

Buttonltem 

;type    of   item 

del 

DriveStr 

; Item  descriptor 

dew 

0,0 

; Item  value    &    bit    flags 

del 

0 

/color  table  ptr    (nil   is 

default) 

CancelButP640 

dew 

5 

; item  # 

dew 

104,204,116,310 

; drect 

dew 

Buttonltem 

; type   of   item 

del 

CancelStr 

;Item  descriptor 

dew 

0,0 

;Item  value   &   bit   flags 

del 

0 

; color   table   ptr    (nil    is 

default) 

ScrollP640 

Special  Note:  Unlike  Scroll  item  in  Get,  Scroll  is  never  used 
in  Put,  since  there  is  not  Multifile  Put  call. 


; item  #  (Dummy  item) 

/dummy  drect  (must  be  0) 

;  type 

/Item  descriptor 

/Item  value  and  bit  flags 

/color  table 


dew 

6 

dew 

0,0,0,0 

dew 

Userltem 

del 

0 

dew 

0,0 

del 

0 
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PathP640 

dew 

7 

/item  # 

dew 

0,10,12,315 

; drect 

dew 

Userltem 

;  type 

del 

PathDraw 

; Item  descriptor  (user  app. specific) 

dew 

0,0 

; Item  value  and  bit  flags 

del 

0 

; color  table 

FilesP640 

dew 

8 

; item  # 

dew 

26,10,88,170 

/Boundary  rect  for  list  manager 

dew 

Userltem+ItemDisable 

;  type 

del 

0 

/ Item  descriptor 

dew 

0,0 

/ Item  value  and  bit  flags 

del 

0 

/color  table 

PromptP640 

dew 

9 

/item  # 

dew 

88,10,100,200 

; drect 

dew 

StatText+ItemDisable 

;  type 

del 

0 

/Item  descriptor 

dew 

0 

/size  of  text  (Text  passed) 

dew 

0 

/Bit  flags 

del 

0 

/color  table 

EditP640 

dew 

io' 

/  item  # 

dew 

100,10,118,194 

/ drect 

dew 

EditLine+ItemDisable 

;  type 

del 

0 

/Item  descriptor 

dew 

63 

/size  of  text 

dew 

0 

/Bit  flags 

del 

0 

/color  table 
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StatTextP64  0 

dew 

11 

; item  # 

dew 

12,10,22,200 

;drect 

dew 

StatText+ItemDisable 

;  type 

del 

KbFreeStr 

;Item  descriptor 

dew 

0 

;size   of   text 

dew 

0 

;Bit    flags 

del 

0 

/color  table 

CreateButP640 

dew 

12 

; item  # 

dew 

29,204,41,310 

;drect 

dew 

Buttonltem 

;  type 

del 

FolderStr 

; Item  descriptor 

dew 

0 

;size   of   text 

dew 

0 

;Bit   flags 

del 

0 

; color  table 

Now,  the  templates  for  320  mode: 


PutDialog320 


dew 

0,0,128,270 

dew 

-1 

dew 

0,0 

del 

SaveButP320 

del 

OpenButP320 

del 

CloseButP320 

del 

NextButP320 

del 

CancelButP320 

del 

ScrollP320 

del 

PathP320 

del 

FilesP320 

del 

PromptP320 

del 

EditP320 

del 

StatTextP320 

del 

CreateButP320 

del 

0 

drect  of  dialog  (320  mode) 

reserved  word 

item  1 

item  2 

item  3 

item  4 

item  5 

DUMMY  item 

item  7 

contains  Boundary  rect 

item  9 

item  10 

item  11 

item  12 
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SaveButP320 

dew 

1 

dew 

93,165,105,265 

dew 

Buttonltem 

del 

SaveStr 

dew 

0,0 

del 

0 

OpenButP320 

dew 

2 

dew 

54,165,66,265 

dew 

Buttonltem 

del 

OpenStr 

dew 

0,0 

del 

0 

CloseButP320 

dew 

3 

dew 

72,165,84,265 

dew 

Buttonltem 

del 

CloseStr 

dew 

0,0 

del 

0 

NextButP320 

dew 

4 

dew 

15,165,27,265 

dew 

Buttonltem 

del 

DriveStr 

dew 

0,0 

del 

0 

CancelButP320 

dew 

5 

dew 

111,165,123,265 

dew 

Buttonltem 

del 

CancelStr 

dew 

0,0 

del 

0 

; item  # 

;drect 

;type  of  item 

; Item  descriptor 

; Item  value  &  bit  flags 

; color  table  ptr  (nil  is  default) 


; item  # 

;drect 

/type  of  item 

;Item  descriptor 

;Item  value  &  bit  flags 

/color  table  ptr  (nil  is  default) 


; item  # 

; drect 

; type  of  item 

;Item  descriptor 

; Item  value  &  bit  flags 

; color  table  ptr  (nil  is  default) 


; item  # 

; drect 

;type  of  item 

; Item  descriptor 

;Item  value  &  bit  flags 

; color  table  ptr  (nil  is  default) 


; item  # 

; drect 

; type  of  item 

;Item  descriptor 

; Item  value  &  bit  flags 

; color  table  ptr  (nil  is  default) 
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ScrollP320 


Special  Note:  Unlike  Scroll  item  in  Get,  Scroll  is  never  used 
in  Put,  since  there  is  not  Multifile  Put  call. 


dew 

6 

; item  #  (Dummy  item) 

dew 

00,00, 

00, 

00 

; drect 

dew 

Userltem 

;  type 

del 

0 

; Item  descriptor 

dew 

0,0 

; Item  value  and  bit  flags 

del 

0 

/color  table 

PathP320 

dew 

7 

; item  # 

dew 

00,10, 

12, 

265 

; drect 

dew 

Userltem 

;  type 

del 

PathDraw 

; Item  descriptor 

dew 

0,0 

;Item  value  and  bit  flags 

del 

0 

; color  table 

FilesP320 

dew 

8 

; item  # 

dew 

26,10, 

88, 

145 

/Boundary  rect  for  list  manager 

dew 

Userltem+ItemDis 

able 

/  type 

del 

0 

/Item  descriptor 

dew 

0,0 

/Item  value  and  bit  flags 

del 

0 

/color  table 

PromptP320 

dew 

9 

/ item  # 

dew 

88,10, 

100 

,170 

/ drect 

dew 

StatText+ItemDis 

able 

/  type 

del 

0 

/Item  descriptor  (Text  passed) 

dew 

0 

dew 

0 

/Bit  flags 

del 

0 

/color  table 
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EditP320 

dew 

10 

; item  # 

dew 

100 

,10,118,157 

; drect 

dew 

EditLine+ItemDisable 

;  type 

del 

0 

;ltem  descriptor 

dew 

32 

;size   of  text 

dew 

0 

;Bit   flags 

del 

0 

; color  table 

StatTextP320 

dew 

11 

; item  # 

dew 

12, 

10,22,160 

; drect 

dew 

StatText+ItemDisable 

;  type 

del 

KbFreeStr 

; Item  descriptor 

dew 

0 

;size   of   text 

dew 

0 

;Bit   flags 

del 

0 

; color   table 

CreateButP320 

dew 

12 

;item  # 

dew 

33, 

165,45,265 

; drect 

dew 

Buttonltem 

;  type 

del 

FolderStr 

;Item  descriptor 

dew 

0 

;size   of   text 

dew 

0 

;Bit   flags 

del 

0 

; color  table 
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New  or  changed  Standard  File  calls 

The  following  sections  discuss  several  new  or  changed  Standard  File  tool  calls. 


SFAllCaps     $0D17 


This  call  has  been  disabled  in  order  to  show  filenames  exactly  as  entered.  Existing 
programs  may  still  issue  the  call,  but  it  will  have  no  effect. 


Stack  before  call 

Previous  contents 

allCapsFlag 

Word— Not  used 

<— SP 

Stack  after  call 

- 

Previous  contents 

<— SP 

Errors                  None 

C                               extern 

pa 

seal   void  SFAllCaps (allCapsFlag) 

Word 

allCapsFlag; 
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SFGetFile2     $0E17 

Displays  the  standard  Open  File  dialog  box  and  returns  information  about  the  file  selected 
by  the  user.  This  all  differs  from  SFGetFile  in  that  it  uses  Class  1  GS/OS  calls,  thereby 
allowing  selection  of  a  file  with  a  full  name  length  of  up  to  763  characters. 

Parameters 

Stack  before  call 


Previous  contents 


whereX 


whereY 


promptRefDesc 


promptRef     - 


-    filterProcPtr 


typelistPtr      - 


replyPtr 


Stack  after  call 


Word— x  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 
Word— Defines  type  of  reference  in  promptRef 

Long — Reference  to  Pascal  string  for  file  prompt 

Long— Pointer  to  filter  procedure;  NIL  for  none 

Long— Pointer  to  type  list  record;  NIL  for  none 

Long— Pointer  to  new-style  reply  record 
<— SP 


Previous  contents 


Errors 


<— SP 


$1701          badPromptDesc 

Invalid  promptRefDesc  value 

$1704          badReplyNameDesc 

Invalid  reply  record 

nameRefDesc  value 

$1705         badReplyPathDesc 

Invalid  reply  record 

pathRef  Desc  value 

GS/OS  errors 

Returned  unchanged 

♦   Note:  The  GS/OS  buf  f  erTooSmaii  error  can  occur  if  the  output  strings  you  supply 
in  the  reply  record  are  too  small  to  receive  the  resulting  filename  string.  In  this  case, 
the  buffer  will  contain  as  many  name  characters  as  would  fit,  and  the  length  word  will 
contain  the  name  length  the  Standard  File  Operations  Tool  Set  tried  to  return. 
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C  extern  pascal  void  SFGetFile2 (whereX,  whereY, 

promptRefDesc,  promptRef,  f ilterProcPtr, 
typelistPtr,  replyPtr) ; 

Pointer    f ilterProcPtr,  typelistPtr,  replyPtr; 
Word      whereX,  whereY,  promptRefDesc; 
Long      promptRef; 

promptRefDes        Defines  the  type  of  reference  in  promptRef: 

$0000  Reference  in  promptRef  "is  a  pointer  to  a  Pascal  string. 

$0001  Reference  in  promptRef  \s  a  handle  of  a  Pascal  string. 

$0002  Reference  in  promptRef  is  the  resource  ID  of  a  Pascal  string 

filterProcPtr  Pointer  to  a  new-style  filter  procedure,  as  described  in  "New  filter 

procedure  entry  interface"  earlier  in  this  chapter. 
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SFMultiGet2     $1417 


Displays  the  standard  Open  Multifile  dialog  box  and  returns  information  about  the  file  or 
files  selected  by  the  user.  The  all  returns  file  selection  information  in  a  multifile  reply 
record.  Note  that  folders  may  be  included  in  the  list  of  returned  files;  your  program  should 
check  the  file  type  field  before  using  any  returned  filenames. 

Parameters 

Stack  before  call 


Previous  contents 


whereX 


whereY 


promptRefDesc 


promptRef     - 


-    filterProcPtr    - 


typelistPtr      - 


replyPtr 


Stack  after  call 


Word— x  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 
Word— Defines  type  of  reference  in  promptRef 
Long— Reference  to  Pascal  string  for  file  prompt 

Long— Pointer  to  filter  procedure;  NIL  for  none 
Long— Pointer  to  type  list  record;  NIL  for  none 
Long— Pointer  to  multifile  reply  record 
<— SP 


Previous  contents 


Errors 
C 


$1701 


<— SP 

badPromptDesc 


Invalid  promptRefDesc  value 


extern  pascal  void  SFMultiGet2 (whereX,  whereY, 

promptRefDesc,  promptRef,  filterProcPtr, 
typelistPtr,  replyPtr) ; 

Pointer   filterProcPtr,  typelistPtr,  replyPtr; 
Word      whereX,  whereY,  promptRefDesc; 
Long      promptRef; 
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promptRefDesc       Defines  the  type  of  reference  in  promptRef. 

$0000  Reference  in  promptRef  'is  a  pointer  to  a  Pascal  string. 

$0001  Reference  in  promptRef  'is  a  handle  of  a  Pascal  string. 

$0002  Reference  in  promptRef  'is  the  resource  ID  of  a  Pascal  string 

filterProcPtr  Pointer  to  a  new-style  filter  procedure,  as  described  in  "New  filter 

procedure  entry  interface"  earlier  in  this  chapter. 
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SFPGetFile2     $1017 

Displays  a  custom  Open  File  dialog  box  and  returns  information  about  the  file  selected  by 
the  user.  This  call  differs  from  SFGetFiie  in  that  it  uses  Class  1  GS/OS  calls,  thereby 
allowing  selection  of  a  file  with  a  full  name  length  of  up  to  763  characters. 

Parameters 

Stack  before  call 


Previous  contents 


tvhereX 


whereY 


-    itemDrawPtr   - 


promptReJDesc 


-     promptRef     - 


-   filterProcPtr    - 


typelistPtr      - 


-     dlgTempPtr    - 


-  dialogHookPtr  - 


replyPtr 


Stack  after  call 


Word— x  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 
Long— Pointer  to  item  draw  routine;  NIL  for  none 
Word— Defines  type  of  reference  in  promptRef 
Long— Reference  to  Pascal  string  for  file  prompt 

Long— Pointer  to  filter  procedure;  NIL  for  none 

Long— Pointer  to  type  list  record;  NIL  for  none 

Long— Pointer  to  dialog  template 

Long— Pointer  to  routine  to  handle  item  hits 

Long — Pointer  to  new-style  reply  record 
<— SP 


Previous  contents 


Errors 


<— SP 


$1701 

badPromptDesc 

Invalid  promptRefDesc  value 

$1704 

badReplyNameDesc 

Invalid  reply  record 
nameRefDesc  value 

$1705 

badReplyPathDesc 

Invalid  reply  record 
pathRef  Desc  value 

GS/OS 

errors 

Returned  unchanged 
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♦   Note:  The  GS/OS  buf  f  erTooSmaii  error  can  occur  if  the  output  strings  you  supply 
in  the  reply  record  are  too  small  to  receive  the  resulting  filename  string.  In  this  case, 
the  buffer  will  contain  as  many  name  characters  as  would  fit,  and  the  length  word  will 
contain  the  name  length  the  Standard  File  Operations  Tool  Set  tried  to  return. 


extern  pascal  void  SFPGetFile2 (whereX,  whereY, 

itemDrawPtr,  promptRefDesc,  promptRef, 
filterProcPtr,  typelistPtr,  dlgTempPtr, 
dialogHookPtr,  replyPtr) ; 

Pointer   itemDrawPtr,  filterProcPtr,  typelistPtr, 

dlgTempPtr,  dialogHookPtr,  replyPtr; 
Word      whereX,  whereY,  promptRefDesc; 
Long      promptRef; 


itemDrawPtr 


Pointer  to  a  custom  item-drawing  routine,  as  described  in  "Custom 
item  drawing  routines"  earlier  in  this  chapter. 


promptRefDesc       Defines  the  type  of  reference  in  promptRef. 

$0000  Reference  in  promptRef  'is  a  pointer  to  a  Pascal  string. 

$0001  Reference  in  promptRef  'is  a  handle  to  a  Pascal  string. 

$0002  Reference  in  promptRef  is  the  resource  ID  to  a  Pascal  string 

filterProcPtr  Pointer  to  a  new-style  filter  procedure,  as  described  in  "New  filter 

procedure  entry  interface"  earlier  in  this  chapter. 

dlgTempPtr,  dialogHookPtr 

For  more  information  about  these  fields,  see  the  discussion  of  the 
SFPutFile  call  in  Chapter  22,  "Standard  File  Operations  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference. 
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SFPMultiGet2     $1517 

Displays  a  custom  Open  Multifile  dialog  box  and  returns  information  about  the  file  or  files 
selected  by  the  user.  The  call  returns  file  selection  information  in  a  multifile  reply  record. 
Note  that  folders  may  be  included  in  the  list  of  returned  files;  your  program  should  check 
the  file  type  field  before  using  any  returned  filenames. 

Parameters 

Stack  before  call 


Previous  contents 


wnereX 


whereY 


-    UemDrawPtr   - 


promptRefDesc 


promptRef     - 


-   filterProcPtr    - 


typelistPtr      - 


-     dlgTempPtr    - 


-  dialogHookPtr  - 


replyPtr 


Stack  after  call 


Word— x  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 

Long— Pointer  to  item  draw  routine;  NIL  for  none 

Word— Defines  type  of  reference  in  promptRef 

Long— Reference  to  Pascal  string  for  file  prompt 

Long— Pointer  to  filter  procedure;  NIL  for  none 
Long— Pointer  to  type  list  record;  NIL  for  none 
Long— Pointer  to  dialog  template 
Long— Pointer  to  routine  to  handle  item  hits 
Long— Pointer  to  multifile  reply  record 
<— SP 


Previous  contents 


Errors 


<— SP 
$1701  badPromptDesc 


Invalid  promptRefDesc  value 
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C  extern  pascal  void  SFPMultiGet2 (whereX,  whereY, 

itemDrawPtr,  promptRefDesc,  promptRef, 
filterProcPtr,  typelistPtr,  dlgTempPtr, 
dialogHookPtr,  replyPtr) ; 

Pointer   itemDrawPtr,  filterProcPtr,  typelistPtr, 

dlgTempPtr,  dialogHookPtr,  replyPtr; 
Word      whereX,  whereY,  promptRefDesc; 
Long      promptRef; 

itemDrawPtr         Pointer  to  a  custom  item-drawing  routine,  as  described  in  "Custom 
item  drawing  routines"  earlier  in  this  chapter. 

promptRefDesc       Defines  the  type  of  reference  in  promptRef. 

$0000  Reference  in  promptRef  is  a  pointer  to  a  Pascal  string. 

$0001  Reference  in  promptRef  is  a  handle  of  a  Pascal  string. 

$0002  Reference  in  promptRef  is  the  resource  ID  of  a  Pascal  string 

filterProcPtr  Pointer  to  a  new-style  filter  procedure,  as  described  in  "New  filter 

procedure  entry  interface"  earlier  in  this  chapter. 

dlgTempPtr,  dialogHookPtr 

For  more  information  about  these  fields,  see  the  discussion  of  the 
SFPutFile  call  in  Chapter  22,  "Standard  File  Operations  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference. 
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SFPPutFile2     $1117 

Displays  a  custom  Save  File  dialog  box  and  returns  information  about  the  file 
specification  entered  by  the  user.  This  call  performs  the  same  function  as  SFPPutFiie, 
but  uses  Class  1  GS/OS  calls,  allowing  the  user  to  specify  a  full  filename.  In  addition,  this 
call  does  not  support  the  maxLen  parameter  provided  in  SFPPutFiie.  This  parameter 
allowed  the  calling  program  to  limit  the  filename  length. 

Parameters 

Stack  before  call 


Previous  contents 


whereX 


whereY 


-    itemDrawPtr   - 


promptRefDesc 


promptRef     - 


origNameRefDesc 


origNameRef   - 


-     dlgTempPtr    - 


-  dialogHookPtr  - 


replyPtr 


Stack  after  call 


Word— x  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 

Long— Pointer  to  item  draw  routine;  NIL  for  none 

Word — Defines  type  of  reference  in  promptRef 

Long— Reference  to  Pascal  string  for  file  prompt 

Word— Defines  type  of  reference  in  origNameRef 

Long— Reference  to  GS/OS  Class  1  Input  String  with  default  name 

Long— Pointer  to  dialog  template 

Long— Pointer  to  routine  to  handle  item  hits 

Long— Pointer  to  new-style  reply  record 
<— SP 


Previous  contents 


-SP 
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Errors 


$1701  badPromptDesc 

$1702  badOrigNameDesc 

$1704  badReplyNameDesc 

$1705  badReplyPathDesc 

GS/OS  errors 


Invalid  protnptRefDesc  value 
Invalid  origNameDesc  value 
Invalid  reply  record 
nameRef  Desc  value 
Invalid  reply  record 
pathRefDesc  value 
Returned  unchanged 


♦   Note:  The  GS/OS  bufferTooSmaii  error  can  occur  if  the  output  strings  you  supply 
in  the  Reply  record  are  too  small  to  receive  the  resulting  filename  string.  In  this  case, 
the  buffer  will  contain  as  many  name  characters  as  would  fit,  and  the  length  word  will 
contain  the  name  length  the  Standard  File  Operations  Tool  Set  tried  to  return. 


C  extern  pascal  void  SFPPutFile2 (whereX,  whereY, 

itemDrawPtr,  promptRefDesc,  promptRef, 
origNameRefDesc,  origNameRef ,  dlgTempPtr, 
dialogHookPtr,  replyPtr) ; 

Pointer    itemDrawPtr,  dlgTempPtr,  dialogHookPtr, 

replyPtr; 
Word      whereX,  whereY,  promptRefDesc, 
origNameRefDesc; 
Long      promptRef,  origNameRef; 

itemDrawPtr         Pointer  to  a  custom  item-drawing  routine,  as  described  in  "Custom 
item  drawing  routines". 

promptRefDesc       Defines  the  type  of  reference  in  promptRef, 


$0000 
$0001 
$0002 

origNameReJDesc 

$0000 

$0001 

$0002 


Reference  in  promptRef  \s  a  pointer  to  a  Pascal  string. 
Reference  in  promptRef  'is  a  handle  of  a  Pascal  string. 
Reference  in  promptRef  is  the  resource  ID  of  a  Pascal  string 

Defines  the  type  of  reference  in  origNameRef 

Reference  in  origNameRef  'is  a  pointer  to  a  GS/OS  Class  1  Input 

string. 

Reference  in  origNameRef  'is  a  handle  to  a  GS/OS  Class  1  Input 

string. 

Reference  in  origNameRef  'is  the  resource  ID  to  a  GS/OS  Class  1 

Input  string 
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origNameRef         Reference  to  a  GS/OS  Class  1  Input  string.  On  input  to 

SFPPutFiie2,  this  string  contains  the  default  filename  for  the  Put 
operation.  On  output,  this  string  contains  the  string  confirmed  by  the 
user,  which  may  not  be  the  same  as  the  default  value. 

dlgTempPtr,  dialogHookPtr 

For  more  information  about  these  fields,  see  the  discussion  of  the 
SFPutFile  call  in  Chapter  22,  "Standard  File  Operations  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference. 
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SFPutFile2     $0F17 

Displays  the  standard  Save  File  dialog  box  and  returns  the  file  specification  entered  by  the 
user.  This  call  performs  the  same  function  as  SFPutFiie,  but  uses  Class  1  GS/OS  calls, 
allowing  the  user  to  specify  a  full  filename.  In  addition,  this  call  does  not  support  the 
maxLen  parameter  provided  in  SFPutFiie.  This  parameter  allowed  the  calling  program 
to  limit  the  filename  length. 

Parameters 

Stack  before  call 


Previous  contents 


whereX 


whereY 


promptRe/Desc 


promptRef     - 


origNameReJDesc 


-    origNameRef   - 


replyPtr 


Stack  after  call 


Word— x  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 
Word— Defines  type  of  reference  in  promptRef 

Long— Reference  to  Pascal  string  for  file  prompt 

Word— Defines  type  of  reference  in  origNameRef 

Long— Reference  to  GS/OS  Class  1  Input  String  with  default  name 

Long— Pointer  to  a  new-style  reply  record 
<— SP 


Previous  contents 


Errors 


<— SP 


$1701 

badPromptDesc 

Invalid  promptRefDesc  value 

$1702 

badOrigNameDesc 

Invalid  origNameDesc  value 

$1704 

badReplyNameDesc 

Invalid  reply  record 
nameRef  Desc  value 

$1705 

badReplyPathDesc 

Invalid  reply  record 
pathRef  Desc  value 

GS/OS 

errors 

Returned  unchanged 
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♦   Note:  The  GS/OS  buf  f  erTooSmaii  error  can  occur  if  the  output  strings  you  supply 
in  the  Reply  record  are  too  small  to  receive  the  resulting  filename  string.  In  this  case, 
the  buffer  will  contain  as  many  name  characters  as  would  fit,  and  the  length  word  will 
contain  the  name  length  the  Standard  File  Operations  Tool  Set  tried  to  return. 


C  extern  pascal  void  SFPutFile2 (whereX,  whereY, 

promptRefDesc,  promptRef,  origNameRefDesc, 
origNameRef ,  replyPtr) ; 

Pointer   replyPtr; 

Word      whereX,  whereY,  promptRefDesc, 

origNameRefDesc; 

Long      promptRef,  origNameRef; 

promptRefDesc       Defines  the  type  of  reference  in  promptRef. 


$0000 
$0001 
$0002 

origNameRefDesc 

$0000 

$0001 

$0002 

origNameRef 


Reference  in  promptRef  is  a  pointer  to  a  Pascal  string. 
Reference  in  promptRef  is  a  handle  of  a  Pascal  string. 
Reference  in  promptRef  is  the  resource  ID  of  a  Pascal  string 

Defines  the  type  of  reference  in  origNameRef 

Reference  in  origNameRef  is  a  pointer  to  a  GS/OS  Class  1  Input 

string. 

Reference  in  origNameRef  is  a  handle  of  a  GS/OS  Class  1  Input 

string. 

Reference  in  origNameRef  is  the  resource  ID  of  a  GS/OS  Class  1 

Input  string 

Reference  to  a  GS/OS  Class  1  Input  string.  On  input  to  SFPutFiie2, 
this  string  contains  the  default  filename  for  the  Put  operation.  On 
output,  this  string  contains  the  string  confirmed  by  the  user,  which 
may  not  be  the  same  as  the  default  value. 
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SFReScan     $1317 

Forces  the  system  to  re-build  and  re-display  the  current  list  of  files.  Your  program  may 
specify  a  new  file  type  list  or  filter  procedure. 

Make  this  call  only  while  SFPGetFiie,  SFPGetFiie2,  or  SFPMuitiGet2  are  running, 
and  only  from  within  a  dialog  hook  routine  (for  information  on  dialog  hook  routines,  see 
the  description  of  SFPGetFiie  in  Chapter  22,  "Standard  File  Operations  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference). 

Parameters 

Stack  before  call 


Previous  contents 


-    filterProcPtr 


typelistPtr 


Long— Pointer  to  filter  procedure;  NIL  for  no  change 

Long— Pointer  to  type  list  record;  NIL  for  no  change 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1706 


<— SP 

badCall 


Neither  SFPGetFiie, 
SFPGetFile2, nor 
SFPMuitiGet2  is  active 


extern  pascal  void  SFReScan (filterProcPtr, 
typelistPtr) ; 

Pointer        filterProcPtr,    typelistPtr; 


Chapter  48    Standard  File  Update     4841 


Apple  1IGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


SFShowInvisible     $1217 


Controls  display  of  invisible  files.  When  the  Standard  File  Operations  Tool  Set  initializes 
itself,  invisible  files  are  not  displayed  and  are  not  passed  to  filter  procedures. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


invisibleState 


Stack  after  call 


Word— Space  for  result 

Word— Flag:  1  -  display  invisible  files;  0  -  no  display  (default) 

<— SP 


Previous  contents 


oldState 


Errors 
C 


None 


Word— Previous  setting  of  invisible  flag 
<— SP 


extern  pascal  word  SFShowInvisible (invisibleState) ; 
Word      invisibleState; 
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Standard  File  error  codes 


This  section  lists  all  valid  Standard  File  error  codes. 


Value 


Name 


Definition 


$1701 

badPromptDesc 

$1702 

badOrigNameDesc 

$1704 

badReplyNameDesc 

$1705 

badReplyPathDesc 

$1706 

badCall 

Invalid  promptRefDesc  value 

Invalid  origNameDesc  value 

Invalid  reply  record  nameRef  Desc 
value 

Invalid  reply  record  pathRef  Desc 
value 

Neither  SFPGetFile,  SFPGetFile2, 

nor  SFPMuitiGet2  is  active 
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Chapter  49   TextEdit  Tool  Set 


This  chapter  documents  the  features  of  the  new  TextEdit  tool  set.  This  is 
a  new  tool  set,  not  previously  documented  in  the 
Apple  IIGS  Toolbox  Reference. 
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About  the  TextEdit  Tool  Set 

The  TextEdit  Tool  Set  provides  basic  text  editing  capabilities  for  any  application.  You 
can  use  TextEdit  to  support  anything  from  a  simple  text-based  dialog  box  to  a  complete 
text  editor.  While  it  has  been  loosely  based  on  the  Macintosh  tool,  TextEdit  for  the  Apple 
IIGS  includes  many  enhancements  that  expand  both  the  flexibility  and  functionality  of  the 
tool  set. 

TextEdit  for  the  Apple  IIGS  supports  a  number  of  capabilities  and  features,  including: 

■  Text  insertion,  deletion,  selection,  copying,  cutting  and  pasting,  using  standard 
keyboard  and  mouse  interfaces 

■  Editing  very  large  documents,  up  to  the  limit  of  system  memory 

■  Word  wrap,  which  avoids  splitting  words  at  the  right  text  edge 

■  Optional  support  for  intelligent  cut  and  paste,  which  eliminates  the  need  for  the  user 
to  add  or  remove  extra  spaces  after  pasting  word-based  selections 

■  Style  variations  in  the  text,  affecting  text  font,  style,  size  or  color 
Formatting  for  margins,  indentation,  justification,  and  tabs 
Left-justified  tabs,  either  evenly  spaced  or  at  specified  locations 
Vertical  scrolling  of  text  that  extends  beyond  the  current  display  window 
Vertical  scroll  bar 

The  following  several  paragraphs  discuss  general  TextEdit  concepts,  and  present  more 
detail  on  some  TextEdit  features. 

TextEdit  provides  your  program  with  the  facilities  to  create,  display,  and  manage  one  or 
more  windows  of  editable  text.  These  windows  can  be  controls  (such  as  the  text  in  a 
dialog  box  or  the  text  window  for  an  editor)  or  independently  managed  by  your 
application.  The  Control  Manager  and  the  Window  Manager  help  your  program  manage 
TextEdit  controls;  your  program  is  solely  responsible  for  TextEdit  windows  that  are  not 
controls.  All  TextEdit  windows,  whether  or  not  they  are  controls,  are  called  records  or 
TextEdit  records. 

Since  there  can  be  many  TextEdit  records  displayed  at  the  same  time,  TextEdit  provides 
a  mechanism  for  distinguishing  between  them  that  is  based  upon  the  mechanism  used  by 
the  Control  Manager  to  move  among  controls  on  the  screen.  The  current  or  active  TextEdit 
record  is  referred  to  as  the  target  record.  That  record  receives  all  user  keystrokes  and 
mouse  commands.  The  user  can  switch  between  TextEdit  records  by  pressing  the  Tab  key 
(if  your  program  has  enabled  that  option)  or  by  clicking  in  the  appropriate  record. 
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TextEdit  maintains  a  number  of  data  structures  for  each  record.  The  TERecord  is  the 
main  structure  for  a  TextEdit  record.  All  control  information  needed  for  the  record  is 
either  stored  in,  or  is  accessible  through,  the  TERecord.  In  general,  your  program  need 
not  access  or  modify  the  TERecord  unless  you  want  to  use  some  of  TextEdit's  internal 
features.  Your  program  creates  a  TextEdit  record,  and  its  TERecord,  by  formatting  a 
TEParamBiock  and  passing  that  structure  to  the  TENew  tool  call.  The  TERecord  is  an 
extension  of  the  generic  control  record  defined  by  the  Control  Manager. 

For  each  TextEdit  record,  your  program  can  instruct  TextEdit  to  use  intelligent  (or  smart) 
cut  and  paste.  The  goal  of  intelligent  cut  and  paste  is  to  eliminate  the  need  for  the  user  to 
insert  spaces  to  fix  a  paste.  With  intelligent  cut  and  paste  enabled,  TextEdit  will  make  the 
following  adjustments  to  the  current  selection: 

■  When  text  is  cut,  remove  all  leading  spaces;  if  there  are  no  leading  spaces,  remove  all 
trailing  spaces 

■  When  text  is  pasted,  if  the  current  selection  is  adjacent  to  a  nonspace  character, 
TextEdit  first  inserts  a  space,  then  the  text 

By  making  these  adjustments,  intelligent  cut  and  paste  allows  the  user  to  select  a  word  (by 
double-clicking  the  mouse,  for  instance),  and  cut  and  paste  that  selected  text  without 
adding  or  removing  any  space  characters.  Your  program  specifies  intelligent  cut  and  paste 
by  setting  a  bit  flag  in  the  textFiags  field  of  the  TEParamBiock  used  to  create  the 
record. 

TextEdit  supports  four  types  of  text  justification:  left,  center,  right,  and  full. 
Left-justified  text  lies  flush  with  the  left  margin,  with  ragged  right  edges.  Right-justified 
text  is  flush  with  the  right  margin,  with  ragged  left  edges.  Each  line  of  centered  text  is 
centered  between  the  left  and  right  margins.  Fully  justified  text  is  blocked  flush  with  both 
left  and  right  margins;  TextEdit  pads  spaces  with  extra  pixels  to  fully  justify  the  text.  Your 
program  specifies  the  type  of  justification  for  a  TextEdit  record  as  part  of  the  initial  style 
information  in  the  TEParamBiock  for  the  record.  Your  program  can  change  the  text 
justification  for  a  record  with  the  TESetRuier  tool  call. 

TextEdit  supports  tabs  in  two  ways.  Regular  tabs  are  spaced  evenly  in  the  text,  at 
consistent  pixel  intervals.  Absolute  tabs  reside  at  specified  pixel  locations  and  can  be 
spaced  irregularly  in  the  text.  All  TextEdit  tabs  are  left  justified.  Your  program  specifies 
whether  a  TextEdit  records  supports  tabs  and,  if  so,  the  type  and  spacing  for  those  tabs 
in  the  TEParamBiock  for  the  record.  Your  program  can  change  the  tabs  for  a  record  with 
the  TESetRuier  tool  call. 
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TextEdit  call  summary 

The  following  table  summarizes  the  capabilities  of  the  TextEdit  Tool  Set  in  a  grouped 
listing  of  its  tool  calls.  Later  sections  of  this  chapter  discuss  TextEdit,  and  its  capabilities 
and  data  structures  in  greater  detail,  and  define  the  precise  syntax  for  the  TextEdit  tool 
calls. 


Routine 


Description 


Housekeeping  routines 

TEBootlnit 
TEStartUp 

TEShutDown 


TEVersion 
|TEReset 
TEStatus 
Record  and  text  management 

TENew 

TEKill 

TESetText 

TEGetText 

TEGetTextlnfo 


Initializes  TextEdit;  called  only  by  the  Tool  Locator 
Allocates  TextEdit  facilities  for  an  application— must 
precede  any  other  TextEdit  tool  calls 
Frees  TextEdit  facilities  used  by  an  application- 
TextEdit  applications  must  issue  this  call  before 
quitting 

Returns  TextEdit  version  number 
Resets  TextEdit;  called  only  when  the  system  is  reset 
Returns  status  information  about  TextEdit 


Allocates  a  new  TextEdit  record 

Disposes  of  an  old  TextEdit  record 

Sets  the  text  for  an  existing  TextEdit  record 

Returns  the  text  from  an  existing  TextEdit  record 

Returns  information  about  the  text  in  a  TextEdit  record 

Insertion  point  and  selection  range 

TEidie  Provides  processor  time  to  TextEdit  so  that  it  can  blink 

the  cursor  and  perform  background  tasks 

TEActivate  Activates  the  current  selection 

TEDeactivate  Deactivates  the  current  selection 

TECiick  Activates  a  specified  TextEdit  record,  and  selects  text 

within  that  record 

TEUpdate  Redraws  a  TextEdit  record 
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Editing 

TEKey 
TECut 

TECopy 
TEPaste 

TEClear 
TEInsert 
TEReplace 
TEGetSelection 

TESet Selection 

Text  display  and  scrolling 

TEGetSelectionStyle 

TEStyleChange 

TEGetRuler 

TESetRuler 

TEScroll 

TEOffsetToPoint 

TEPointToOffset 

TEPaintText 

Miscellaneous  Routines 

TEGetDefProc 
TEGetlnternalProc 
TEGetLastError 
TECompactRecord 


Inserts  a  character  into  the  target  TextEdit  record 

Cuts  the  current  selection  and  places  it  into  the  desk 

scrap 

Copies  the  current  selection  into  the  desk  scrap 

Pastes  the  contents  of  the  desk  scrap  into  the  text, 

replacing  the  current  selection 

Clears  the  current  selection 

Inserts  the  specified  text  before  the  current  selection 

Replaces  the  current  selection  with  the  specified  text 

Returns  the  starting  and  ending  character  offsets  for  the 

current  selection 

Sets  the  current  selection  to  the  specified  starting  and 

ending  character  offsets 

Returns  style  information  for  the  current  selection 

Changes  the  style  of  the  current  selection 

Returns  format  information  for  a  TextEdit  record 

Sets  format  information  for  a  TextEdit  record 

Scrolls  to  a  specified  line,  text  offset,  or  pixel  position 

Converts  a  text  offset  into  a  point  (in  local 

coordinates) 

Converts  a  point  (in  local  coordinates)  into  a  text 

offset 

Paints  TextEdit  text  into  an  off-screen  port— used  for 

printing 

Returns  a  pointer  to  the  TextEdit  custom  control 

definition  procedure 

Returns  a  pointer  to  the  TextEdit  low-level  routine 

dispatcher 

Returns  the  last  error  code  generated  for  a  TextEdit 

record 

Compresses  the  data  structures  associated  with  a 

TextEdit  record 
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How  to  use  TextEdit 

You  may  choose  between  several  techniques  for  creating  and  controlling  TextEdit  records 

■  Create  a  TextEdit  control  with  the  NewControi2  Control  Manager  tool  call,  and  allow 
TaskMaster  to  manage  the  control  for  you 

■  Create  a  TextEdit  control  with  the  NewControi2  tool  call  and  manage  the  control 
yourself 

■  Create  a  TextEdit  record  that  is  not  a  control  with  the  TENew  TextEdit  tool  call  and 
manage  it  yourself 

The  remainder  of  this  section  discusses  each  of  these  techniques  in  more  detail. 

The  simplest  technique  is  to  create  a  TextEdit  control,  using  either  the  TENew  TextEdit 
tool  call  or  the  NewControi2  Control  Manager  call,  and  use  TaskMaster  to  manage  the 
record  (see  Chapter  25,  "Window  Manager,"  in  the  Toolbox  Reference  for  more  information 
on  TaskMaster).  TaskMaster  handles  all  TextEdit  events  and  user  interaction  for  single- 
style  records.  The  following  pseudo  code  describes  the  basic  program  logic  for  this 
technique. 

Initialize  all  the  tools  including  TextEdit. 
Create  a  new  window. 

Call  TENew.  This  allocates  a  new  TextEdit  record, 
while (  quitFlag  !=  TRUE  ) 

{ 

Call  TaskMaster.  This  handles  all  the  events;  it  inserts  all  the 

keys  that  the  user  types,  handles  all  the  mouse  activity  and 
takes  care  of  blinking  the  cursor.  It  even  calls  TECut, 
TECopy,  TEPaste,  and  TEClear  for  the  TextEdit  record. 
if(  the  user  selects  the  save  item  ) 
{ 

Call  TEGetText.  This  extracts  the  text  and  style  information 
that  the  user  has  typed. 
} 
} 
Dispose  of  the  window.  This  deallocates  the  TextEdit  record  and  all 

other  controls  in  the  window. 
Shutdown  all  the  tools  and  exit. 

Your  application  does  not  need  to  do  anything  if  the  user  presses  a  key,  clicks  the  mouse 
button,  or  selects  a  menu  item.  TaskMaster  and  the  TextEdit  control  definition  procedure 
handle  all  these  standard  events.  The  Window  Manager  will  dispose  of  the  TextEdit 
control  when  your  application  closes  its  window. 
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However,  your  program  does  give  up  some  flexibility  in  exchange  for  the  simplicity  of  this 
approach.  In  order  to  exert  somewhat  more  control  over  the  TextEdit  record,  you  may 
choose  to  create  a  TextEdit  control  and  manage  that  control  in  your  program,  rather  than 
with  TaskMaster.  Your  program  would  then  issue  the  GetNextEvent  Window  Manager 
call  to  trap  user  actions,  and  then  process  those  actions  accordingly.  The  following 
pseudo  code  shows  sample  logic  for  this  approach. 

Initialize  all  the  tools  including  TextEdit. 
Create  a  new  window. 

Call  TENew.  This  allocates  a  new  TextEdit  record, 
while (  quitFlag  !=  TRUE  ) 

{ 

Call  TEIdle.  This  blinks  the  cursor  and  performs  background 

tasks. 

Call  GetNextEvent. 

switch  theEvent .what 

{ 

case  updateEvent: 

Call  DrawControls.  This  draws  the  TextEdit  control 
(and  all  others  in  the  window) 
case  mouseDownEvent : 

Call  FindWindow.  This  determines  where  in  the 

desktop  the  mouse  was  clicked, 
if (  FindWindow  returned  inMenu  ) 

{ 

call  MenuSelect.  This  tracks  the  menu  and 

returns  which  item  the  user  clicked  in. 
switch  theMenuItem 

{ 

case  Cutltem: 

Call  TECut.  This  tells  TextEdit  to  cut 

the  current  selection  into  the  desk 
scrap, 
case  Copyltem: 

Call  TECopy.  This  tells  TextEdit  to  copy 
the  current  selection  into  the  desk 
scrap. 
case  Pasteltem: 

Call  TEPaste.  This  tells  TextEdit  to 
replace  the  current  selection  with  the 
desk  scrap. 
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case  Clearltem: 

Call  TEClear.  This  tells  TextEdit  to 
clear  the  current  selection. 
case  Saveltem: 

Call  TEGetText.  This  extracts  the  text 

and  style  information  that  the  user 
has  typed, 
case  Quitltem: 

Set  the  quitFlag  to  TRUE. 
} 
} 
else  if (  FindWindow  returned  inContent  ) 

{ 

Call  FindControl.  This  returns  which  control 

was  clicked  in. 
if (  FindControl  returned  the  TextEdit  control  ) 

{ 

call  TEClick.  This  tracks  the  mouse 

within  the  TextEdit  record;  it  does 
all  the  selecting  and  all  the 
scrolling. 
} 
} 
else 

{ 

} 
case  keyDownEvent , autoKeyEvent : 

Call  TEKey.  This  inserts  the  key  that  the  user  typed 
into  the  TextEdit  record.  It  also  performs 
editing  operations  if  the  key  is  a  "control  key" 
(like  DELETE,  CTRL-Y,  arrow  keys,  etc) . 
} 

} 

Dispose  of  the  window.  This  deallocates  the  TextEdit  record  and  all 
other  controls  in  the  window. 
Shutdown  all  the  tools  and  exit. 
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Finally,  you  may  choose  to  create  TextEdit  records  that  are  not  controls.  In  this  case,  your 
program  must  not  only  provide  complete  functional  support  for  the  record,  as  shown  in 
the  non-TaskMaster  pseudo  code,  but  also  manage  the  TextEdit  window  itself.  You  must 
use  the  TENew  call  to  create  TextEdit  records  that  are  not  controls.  These  TextEdit 
records  are  not  inserted  into  the  control  list,  so  your  program  may  not  issue  Control 
Manager  calls  to  manipulate  or  control  them.  Similarly,  your  program  may  not  use  Window 
Manager  calls  on  them.  The  following  pseudo  code  presents  sample  logic  for  this 
approach. 

Initialize  all  the  tools  including  TextEdit. 

Create  a  new  window. 

Call  TENew.  This  allocates  a  new  TextEdit  record. 

while (  quitFlag  !=  TRUE  ) 

{ 

Call  TEIdle.  This  blinks  the  cursor  and  performs  background 

tasks. 

Call  GetNextEvent . 

switch  theEvent .what 

{ 

case  updateEvent: 

Call  TEUpdate.  This  draws  the  TextEdit  record. 
case  mouseDownEvent : 

Call  FindWindow.  This  determines  where  in  the  desktop  the 
mouse  was  clicked. 

if (  FindWindow  returned  inMenu  ) 

{ 

call  MenuSelect.  This  tracks  the  menu  and  returns 

which  item  the  user  clicked  in. 
switch  theMenuItem 

{ 

case  Cutltem: 

Call  TECut.  This  tells  TextEdit  to  cut  the 

current  selection  into  the  desk  scrap, 
case  Copyltem: 

Call  TECopy.  This  tells  TextEdit  to  copy  the 
current  selection  into  the  desk  scrap. 
case  Pasteltem: 

Call  TEPaste.  This  tells  TextEdit  to  replace 

the  current  selection  with  the  desk  scrap 
case  Clearltem: 

Call  TEClear.  This  tells  TextEdit  to  clear  the 
current  selection. 
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case  Saveltem: 

Call  TEGetText.  This  extracts  the  text  and 

style  information  that  the  user  has  typed, 
case  Quitltem: 

Set  the  quitFlag  to  TRUE. 

} 
} 
else  if (  FindWindow  returned  inContent  ) 

{ 

Figure  out  whether  the  click  occurred  in  the  TextEdit 

record. 

if (  the  click  occurred  in  the  TextEdit  record  ) 

{ 

call  TEClick.  This  tracks  the  mouse  within  the 

TextEdit  record;  it  does  all  the  selecting 
and  all  the  scrolling. 
} 
} 

else 
{ 

} 
case  keyDownEvent, autoKeyEvent : 

Call  TEKey.  This  inserts  the  key  that  the  user  typed  into 
the  TextEdit  record.  It  also  performs  editing 
operations  if  the  key  is  a  "control  key"  (like  DELETE, 
CTRL-Y,  arrow  keys,  etc) . 
} 

} 

Dispose  of  the  window.  This  deallocates  the  TextEdit  record  and  all 

other  controls  in  the  window. 

Shutdown  all  the  tools  and  exit. 

With  this  technique,  your  program  has  much  more  responsibility.  First,  your  program  must 
issue  the  TEUpdate  call  for  each  record  that  must  be  redrawn,  rather  than  relying  on  the 
Control  Manager  DrawControis  tool  call.  In  addition,  your  program  must  use  the 
TEActivate  and  TEDeactivate  tool  calls  whenever  the  user  switches  between 
TextEdit  records.  Finally,  for  each  mouse-down  event,  your  program  must  determine  in 
which  TextEdit  record  the  user  clicked— FindControi  will  not  work  with  TextEdit 
records  that  are  not  controls. 
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A  Warning  If  you  have  defined  TextEdit  records  that  are  controls  in  a  window, 
you  must  not  also  try  to  define  non-control  TextEdit  records  in  the 
same  window.  ▲ 


All  TextEdit  tool  calls  require  you  to  specify  a  handle  to  the  appropriate  te Record,  so 
that  TextEdit  knows  which  record  to  address.  For  TextEdit  records  that  are  controls,  your 
program  may  specify  a  NULL  value  for  the  TERecord  handle.  TextEdit  will  then  access  the 
currendy  active  TextEdit  control  (the  target  TextEdit  record). 


A  Warning         Never  pass  a  NULL  TERecord  handle  to  access  TextEdit  records  that 
are  not  controls,  a 


Note  that  TextEdit  routines  always  use  the  same  TERecord  layout,  whether  or  not  the 
TextEdit  record  is  a  control.  However,  if  the  TextEdit  record  is  not  a  control,  your 
program  cannot  issue  Control  Manager  tool  calls  for  it. 


Standard  TextEdit  key  sequences 

TextEdit  provides  a  keyboard  and  mouse  interface  that  supports  a  number  of  editing 
keys.  The  following  table  summarizes  the  effect  of  control  keystrokes  and  mouse  clicks: 

Key  Alias  Description 

Left  Arrow         Control-h  Moves  the  insertion  point  to  the  previous  character  in 

the  text 

Command  key  causes  movement  by  word  rather  than  by 
character 

Option  key  moves  the  insertion  point  to  the  beginning 
of  the  previous  line  in  the  text 
Shift  key  extends  the  selection  from  the  current 
insertion  point  back  by  a  character,  word  (if  the 
Command  key  is  also  held  down),  or  line  (if  the  Option 
key  is  also  held  down) 
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Right  Arrow        Control-u 


Up  Arrow  Control-k 


Down  Arrow       Control-j 


Delete 

Clear 
Control-f 

Control-y 


Control-d 


Moves  the  insertion  point  to  the  next  character  in  the 

text 

Command  key  causes  movement  by  word  rather  than  by 

character 

Option  key  moves  the  insertion  point  to  the  end  of  the 

current  line  in  the  text 

Shift  key  extends  the  selection  from  the  current 

insertion  point  forward  by  a  character,  word  (if  the 

Command  key  is  also  held  down),  or  line  (if  the  Option 

key  is  also  held  down) 

Moves  the  insertion  point  up  one  line 

Command  key  moves  the  insertion  point  to  the 

beginning  of  the  current  page 

Option  key  moves  the  insertion  point  to  the  beginning 

of  the  document 

Shift  key  extends  the  selection  from  the  current 

insertion  point  up  by  a  line  or  page  (if  the  Command 

key  is  also  held  down),  or  to  the  beginning  of  the 

document  (if  the  Option  key  is  also  held  down) 

Moves  the  insertion  point  down  one  line 

Command  key  moves  the  insertion  point  to  the  current 

column  position  on  the  last  line  of  the  page 

Option  key  moves  the  insertion  point  to  the  end  of  the 

document 

Shift  key  extends  the  selection  from  the  current 

insertion  point  down  by  a  line  or  page  (if  the  Command 

key  is  also  held  down),  or  to  the  end  of  the  document 

(if  the  Option  key  is  also  held  down) 

If  there  is  no  current  selection,  removes  the  character  to 

the  left  of  the  insertion  point;  if  there  is  a  selection, 

removes  the  selected  text 

Clears  the  current  selection  (does  nothing  if  there  is  no 

selection) 

If  there  is  no  current  selection,  removes  the  character  to 

the  right  of  the  insertion  point;  if  there  is  a  selection, 

removes  the  selected  text 

Removes  all  characters  from  the  insertion  point  to  the 

end  of  the  line,  not  including  any  terminating  ASCII 

return  characters  ($0D) 
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Control-x 
Control-c 
Control-v 

Click 

Double-click 

Triple-click 


Cuts  the  current  selection  into  the  Clipboard  (same  as 

the  TECut  tool  call) 

Copies  the  current  selection  into  the  Clipboard  (same  as 

the  TECopy  tool  call) 

Pastes  the  contents  of  the  clipboard  at  the  current 

insertion  point,  or  in  place  of  any  selected  text  (same 

as  the  TEPaste  tool  call) 

Moves  the  insertion  point— dragging  selects  by 

character 

Selects  a  word— dragging  extends  the  selection  by 

words 

Selects  a  line— dragging  extends  the  selection  by  lines 
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Internal  structure  of  the  TextEdit  Tool  Set 

This  section  discusses  several  topics  relating  to  the  internal  structure  and  function  of  the 
TextEdit  Tool  Set.  This  information  will  not  be  relevant  to  most  application 
programmers,  but  does  provide  insight  into  how  TextEdit  operates,  and  how  to  tailor 
TextEdit  for  special  applications. 


TextEdit  controls  and  the  Control  Manager 


As  has  been  discussed,  TextEdit  records  may  or  may  not  be  controls.  Your  program 
creates  TextEdit  controls  by  issuing  the  NewControi2  Control  Manager  tool  call.  The 
Control  Manager  handles  nearly  all  the  support  calls  needed  to  maintain  the  TextEdit 
record.  However,  you  may  choose  to  use  certain  Control  Manager  tool  calls  with  the 
TextEdit  control.  The  following  tables  list  which  Control  Manager  calls  may  or  may  not  be 
used  with  TextEdit  controls.  In  this  context,  the  TextEdit  control  is  taken  to  include  the 
actual  TextEdit  record  and  its  associated  scroll  bars  and  size  box. 

The  following  Control  Manager  calls  may  be  used  with  TextEdit  controls: 

Call  Description 


DisposeControl 


KillControls 


HideControl 


EraseControl 

ShowControl 

DrawControls 
DrawOneCtl 


Disposes  of  the  TextEdit  control— analogous  to 

TEKiii  TextEdit  tool  call 

Disposes  of  all  controls,  including  the  TextEdit 

controls— analogous  to  tekiii  tool  calls  for  each 

control 

Hides  the  TextEdit  control— note  that  this  call  does 

not  affect  the  status  of  the  control  with  respect  to  user 

keystokes;  if  you  hide  the  target  control,  it  is  still  the 

target  control,  although  no  user  keystrokes  will  be 

displayed 

Erases  the  TextEdit  control— similar  to  Hi  decontrol, 

except  that  EraseControl  does  not  invalidate  the 

boundary  rectangle  for  the  control 

Reshows  the  TextEdit  control,  reversing  the  effect  of 
HideControl  Or  EraseControl 
Draws  all  controls  in  the  window 
Draws  the  specified  TextEdit  control 
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HilightControl 


FindControl 


TestControl 


TrackControl 


MoveControl 
DragControl 
SetCtlRefCon 
GetCtlRefCon 


Activates  or  deactivates  the  TextEdit  control— note 

that  only  hiliteStale  values  of  0  and  255  are  valid 

Returns  point  location  control  identification 

information— returns  partCode  of  130  if  point  is  in  text, 

131  if  point  is  in  vertical  scroll  bar,  and  132  if  point  is  in 

size  box 

Returns  the  same  point  location  information  as 

FindControl,  without  any  control  identification 

Selects  text— actionProcPtr  must  be  set  to  a  negative 

value  (forces  the  Control  Manager  to  use  TextEdit's 

built-in  action  procedure) 

Moves  the  TextEdit  control 

Allows  the  user  to  reposition  the  TextEdit  control 

Sets  the  refCon  field 

Returns  the  contents  of  the  refCon  field 


Your  program  must  not  issue  the  following  Control  Manager  tool  calls  with  a  TextEdit 
control: 

GetCtlTitle 

GetCtlValue 

GetCtlAction 

GetCtlParams 

SetCtlTitle 

SetCtlValue 

SetCtlAction 

SetCtlParams 


TextEdit  filter  procedures  and  hook  routines 

TextEdit  provides  you  with  several  mechanisms  to  tailor  the  operation  of  the  tool  set  to 
the  particular  needs  of  your  application.  Filter  procedures  give  you  a  chance  to  affect  the 
behavior  of  the  tool  set  by  modifying  screen  display  activity  or  user  keystrokes.  Hook 
routines  allow  you  to  replace  standard  TextEdit  code  for  such  functions  as  word  wrap  or 
word  break.  The  following  several  sections  discuss  each  of  the  various  filter  procedures 
and  hook  routines  in  more  detail. 
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Generic  filter  procedure 

TextEdit  provides  a  facility  whereby  your  application  can  supply  special  logic  to  replace 
some  of  the  standard  TextEdit  routines.  The  program  code  that  uses  this  facility  is  called 
a  generic  filter  procedure.  The  generic  filter  procedure  is,  in  turn,  made  up  of  several 
routines  that  address  particular  TextEdit  processing  requirements.  At  present,  there  are 
three  functions  that  generic  filter  routines  can  provide: 

■  Erasing  rectangles  in  the  display  port 

■  Erasing  rectangles  in  the  off-screen  TextEdit  buffer 

■  Updating  the  TextEdit  record  screen  display 

The  TERecord  f  iiterProc  field  contains  a  pointer  to  the  generic  filter  procedure.  If 
this  field  has  a  non-NULL  value,  TextEdit  will  call  the  filter  procedure  to  perform  the 
activities  just  mentioned.  You  set  this  pointer  by  specifying  the  appropriate  value  in  the 
filterProcPtr  field  of  the  TEParamBlock  passed  to  TENew  (orNewControl2) 
when  you  create  the  TextEdit  record.  TextEdit  then  loads  thefiiterProc  field  of  the 
TERecord  from  this  value. 

The  routines  in  the  filter  procedure  must  adhere  to  the  following  rules: 

■  The  routine  must  preserve  the  direct  page  and  data  bank  registers,  and  must  return  in 
full  native  mode. 

■  All  entry  and  exit  parameter  and  status  fields  must  be  passed  through  the  appropriate 
TERecord. 

■  Filter  routines  must  not  issue  TextEdit  tool  calls,  move  memory,  or  cause  memory  to 
be  moved. 

■  Any  application-specific  routine  messages  must  have  message  numbers  greater  than 
$8000— TextEdit  reserves  all  message  number  values  in  the  range  from  $0000  through 
$7FFF. 

TextEdit  invokes  the  generic  filter  procedure  in  full  native  mode  by  executing  a  jsl.  On 
entry  to  the  filter  procedure,  the  stack  is  formatted  as  follows; 


Previous  contents 


Space 


teHandle 


message 


RTL 


Word— Space  for  result 

Long— Handle  to  the  appropriate  TERecord 

Word— Message  number  indicating  action  to  take 

Three  bytes— Return  address 

<— SP 
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On  exit,  the  filter  procedure  must  format  the  stack  as  follows: 
Previous  contents 


Result 


Word— Result  code 
<— SP 

result  Indicates  whether  the  filter  procedure  handled  the  message.  If  the 

field  is  set  to  $0000,  then  TextEdit  will  perform  its  standard 
processing.  If  the  field  is  nonzero,  then  the  filter  procedure  handled 
the  message,  and  TextEdit  does  not  perform  its  standard  processing. 

The  following  sections  discuss  each  defined  filter  procedure  message,  defining  the 
actions  the  filter  procedure  is  to  take  and  the  affected  TERecord  fields. 

doEraseRect  ($0001) 

The  filter  procedure  is  to  erase  a  rectangle  in  the  display  port  for  the  current  TextEdit 
record.  TextEdit  has  already  set  up  the  port  for  the  filter  routine. 

TextEdit  provides  this  routine  to  support  applications  that  maintain  overlaying  objects 
on  the  display.  Under  such  circumstances,  the  application  must  decide  what  object  to 
make  visible  after  the  user  has  caused  a  currently  visible  object  to  be  deleted. 

Input: 


TiR.cord  field  Contents 


theFiiterRect  Specifies  the  rectangle  to  erase,  expressed  in  local 

coordinates  for  the  port 

Output: 

None 
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doEraseBuffer  ($0002) 

The  filter  procedure  is  to  move  a  rectangle  from  TextEdit's  offscreen  buffer  to  the  display 
port.  The  TERecord  contains  information  defining  the  source  and  destination  data 
locations.  TextEdit  has  already  set  up  the  port  for  the  filter  routine. 

This  routine  is  used  in  much  the  same  way  as  doEraseRect,  except  that  it  operates  off- 
screen, rather  than  on-screen. 

Input: 

TKRacoxd  field  Contents 

theFiiterRect  Specifies  the  rectangle  to  erase,  expressed  in  local 

coordinates  for  the  offscreen  buffer  port 
theBuf  f  erVPos  Vertical  position  corresponding  to  the  top  of  the 

destination  buffer  in  the  display  port,  expressed  in  local 

coordinates  for  the  port 
theBuf  ferHPos  Horizontal  position  corresponding  to  the  left  edge  of 

the  destination  buffer  in  the  display  port,  expressed  in 

local  coordinates  for  the  port 

Output: 

None 
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doRectChanged  ($0003) 

The  filter  procedure  is  to  handle  a  change  to  the  display  window  for  the  TextEdit  record. 
Note  that  TextEdit  has  not  set  up  the  port;  the  filter  procedure  must  obtain  the  port  from 
the  inPort  field  of  the  TERecord,  and  set  up  the  display  port. 

With  this  routine  your  application  can  maintain  an  off-screen  copy  of  its  TextEdit 
display.  Whenever  TextEdit  updates  the  screen,  it  issues  this  message  to  the  generic  filter 
procedure,  which  can  update  the  saved  screen  copy. 

Input: 


TERacord  field 


Contents 


theFilterRect 

Output: 

None 


Specifies  the  rectangle  that  changed,  expressed  in  local 
coordinates  for  the  port 
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Keystroke  filter  procedure 

TextEdit  also  provides  a  mechanism  for  applications  to  supply  custom  keystroke 
processing  for  a  TextEdit  record.  TextEdit's  internal  keystroke  routine  supports  the 
standard  keyboard  interface  described  in  "Standard  TextEdit  key  sequences"  in  this 
chapter.  Custom  keystroke  processing  may  support  different  keyboard  mappings  or 
macro  facilities. 

The  keyFiiter  field  of  a  TERecord  can  contain  a  pointer  to  a  keystroke  filter 
procedure.  If  keyFiiter  is  NULL,  TextEdit  uses  its  standard  keystroke  routine.  If 
keyFiiter  is  non-NULL,  TextEdit  calls  the  routine  pointed  to  by  keyFiiter  to 
process  all  user  keyboard  input. 

Keystroke  filter  procedures  must  follow  many  of  the  same  rules  established  for  generic 
filter  procedures: 

■  The  procedure  must  preserve  the  direct-page  and  data  bank  registers,  and  must  return 
in  full  native  mode. 

■  Keystroke  filter  procedures  must  not  issue  TextEdit  tool  calls. 

TextEdit  invokes  the  keystroke  filter  procedure  in  full  native  mode  by  executing  a  jsl. 
Fields  in  the  KeyRecord  TERecord  sub-structure  contain  information  defining  the  data 
to  be  processed: 

K*y r*  cord  field  Contents 


theChar 
theModifiers 


thelnputHandle 


This  field  contains  the  keystroke  to  process. 

This  field  contains  flags  indicating  the 
state  of  the  modifier  keys  at  the  time  the  key  was 
pressed;  the  keystroke  is  contained  in  theChar  and 
thelnputHandle. 
Handle  to  a  copy  of  theChar. 


TextEdit  loads  additional  control  information  onto  the  stack.  On  entry  to  the  filter 
procedure,  the  stack  is  formatted  as  follows: 


Previous  contents 


teHandle 


type 


RTL 


Long— Handle  to  the  appropriate  TERecord 
Word— Type  of  data  to  be  processed 
Three  bytes— Return  address 
<— SP 
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type  Indicates  the  type  of  data  to  be  processed: 

$0001  KeyRecord  theChar  field  contains  the  single  character  to  be 

processed 
$0002  Reserved 

The  keystroke  filter  procedure  is  now  free  to  perform  whatever  processing  is  appropriate. 
For  example,  it  may  change  the  input  keystroke  value  in  order  to  support  a  different 
mapping  of  the  standard  TextEdit  keyboard  functions.  Or,  the  routine  may  expand  the 
keystroke  in  theChar  into  a  block  of  text  to  be  inserted  at  the  current  location.  The 
routine  then  formats  the  appropriate  return  data  into  the  KeyRecord  fields  and  returns 
control  to  TextEdit  by  issuing  an  rtl  instruction  (after  removing  all  input  parameters 
from  the  stack). 

On  exit,  the  filter  procedure  must  format  the  stack  as  follows: 
Previous  contents 


<— SP 


Chapter  49  TextEdit     49-21 


Apple  11GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


The  filter  procedure  indicates  what  action  TextEdit  is  to  take  with  the  theOpCode  field 
in  the  KeyRecord.  This  code  in  turn  governs  how  TextEdit  interprets  the  remainder  of 
the  returned  KeyRecord.  Valid  theOpCode  values  are: 


th«OpCod« 


Value 


opNormal  $0000 

opNothing  $0002 

opReplaceText  $0004 


opMoveCursor 

$0006 

opExtendCursor 

$0008 

opCut 

$000A 

opCopy 

$000C 

opPaste 

$000E 

TextEdit  action 


opClear 


$0010 


TextEdit  performs  its  standard  processing  on  the 

character  stored  in  the  location  referred  to  by 

thelnputHandle 

TextEdit  ignores  the  keystroke 

TextEdit  inserts  the  text  referred  to  by 

thelnputHandle  in  place  of  the  current  selection  in 

the  record;  if  there  is  no  current  selection,  TextEdit 

inserts  the  text  at  the  current  insertion  point— if 

thelnputHandle  has  0  size,  TextEdit  deletes  the 

current  selection  and  inserts  nothing 

TextEdit  moves  the  cursor  to  the  location  specified  by 

cursorOf f set 

TextEdit  extends  the  current  selection  from  its  anchor 

point  to  the  location  specified  by  cursorOf  f  set 

TextEdit  moves  the  current  selection  and  to  the  desk 

scrap 

TextEdit  copies  the  current  selection  to  the  desk  scrap 

TextEdit  inserts  the  contents  of  the  desk  scrap  in  place 

of  the  current  selection 

TextEdit  clears  the  current  selection 
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The  following  table  summarizes  the  contents  of  the  KeyRecord  on  return  from  the 
keystroke  filter  procedure: 


Kayfcacord  field 


Contents 


theChar 

theModifiers 

thelnputHandle 


cursorOffset 


theOpCode 


Unchanged 

Contains  changed  modifiers  (only  for  opNormai) 

Handle  to  replacement  text  (only  for  opNormai  and 

opRepiaceText),  length  of  text  indicated  by  size  of 

handle; 

If  TextEdit  is  to  move  the  cursor  (theOpCode  is  set  to 

either  opMoveCursor  or  opExtendCursor),  this 

field  contains  the  new  cursor  location;  otherwise, 

TextEdit  ignores  this  field. 

Specifies  next  action  for  TextEdit 
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Word  wrap  hook 

Your  program  may  supply  its  own  routine  to  handle  word  wrap.  This  word  wrap  hook 
routine  determines  whether  a  character  string  typed  by  the  user  fits  on  the  current  line 
(does  not  wrap)  or  needs  to  begin  a  new  line  (does  wrap).  TextEdit  then  displays  the 
character  string  on  the  appropriate  line. 

TextEdit  determines  whether  to  call  a  custom  word  wrap  routine  by  examining  the 
wordwrapHook  TERecord  field  for  the  TextEdit  record.  If  that  field  is  NULL,  TextEdit 
uses  its  standard  word  wrap  routine.  If  that  field  is  non-NULL,  TextEdit  calls  the  routine 
pointed  to  by  that  field  whenever  a  word  wrap  decision  is  required.  Your  program  sets  this 
pointer  by  directly  modifying  the  wordwrapHook  field  of  the  appropriate  TERecord. 

Word  wrap  hook  routines  must  follow  many  of  the  rules  established  for  generic  filter 
procedures: 

■  The  routine  must  preserve  the  direct-page  and  data  bank  registers,  and  must  return  in 
full  native  mode. 

■  Word  wrap  routines  must  not  issue  TextEdit  tool  calls,  move  memory,  or  cause 
memory  to  be  moved. 

TextEdit  invokes  the  word  wrap  hook  procedure  in  full  native  mode  by  executing  a  jsl. 
Entry  parameters  refer  the  procedure  to  the  correct  TERecord  and  character.  On  exit,  the 
word  wrap  procedure  returns  a  flag  indicating  whether  the  character  caused  a  word  wrap. 

On  entry  to  the  procedure,  the  stack  is  formatted  as  follows: 


Previous  contents 


Space 


teHandle 


theChar 


RTL 


Word— Space  for  result 

Long— Handle  to  the  appropriate  TERecord 

Word— Character  to  check 

Three  bytes— Return  address 

<— SP 


On  exit,  the  filter  procedure  must  format  the  stack  as  follows: 


Previous  contents 


wrapFlag 


Word— Flag  indicating  wrap  status 
<— SP 
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wrapFlag  Indicates  wrap  status  for  the  current  character: 

$0000  Not  a  word  wrap  (TextEdit  will  leave  the  word  on  the  current 

line) 
$FFFF  Word  wrap  (TextEdit  will  move  the  word  to  the  next  line) 
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Word  break  hook 

Your  program  may  supply  its  own  routine  to  determine  word  breaks  when  the  user  is 
selecting  text  by  words  (user  has  double-clicked  on  a  word  and  is  now  extending  that 
selection).  This  word  break  hook  routine  decides  whether  the  cursor  resides  at  a  break 
between  words.  If  so,  TextEdit  includes  the  next  word  in  the  current  selection. 

TextEdit  determines  whether  to  call  a  custom  word  wrap  routine  by  examining  the 
wordBreakHook  TERecord  field  for  the  TextEdit  record.  If  that  field  is  NULL, 
TextEdit  uses  its  standard  word  break  routine.  If  that  field  is  non-NULL,  TextEdit  calls  the 
routine  pointed  to  by  that  field  whenever  a  word  break  decision  is  required.  Your  program 
sets  this  pointer  by  direcdy  modifying  the  wordBreakHook  field  of  the  appropriate 
TERecord. 

Word  break  hook  routines  must  follow  many  of  the  rules  established  for  generic  filter 
procedures: 

■  The  routine  must  preserve  the  direct-page  and  data  bank  registers,  and  must  return  in 
full  native  mode. 

■  Word  break  routines  must  not  issue  TextEdit  tool  calls,  move  memory,  or  cause 
memory  to  be  moved. 

TextEdit  invokes  the  word  break  hook  procedure  in  full  native  mode  by  executing  a  jsl. 
Entry  parameters  refer  the  procedure  to  the  correct  TERecord  and  character.  On  exit,  the 
word  break  procedure  returns  a  flag  indicating  whether  the  character  constitues  a  word 
break. 

On  entry  to  the  procedure,  the  stack  is  formatted  as  follows: 


Previous  contents 


Space 


teHandle 


theChar 


RTL 


Word— Space  for  result 

Long— Handle  to  the  appropriate  TERecord 

Word— Character  to  check 

Three  bytes— Return  address 

<— SP 


On  exit,  the  filter  procedure  must  format  the  stack  as  follows: 


Previous  contents 


breakFlag 


Word— Flag  indicating  break  status 
<— SP 
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breakFlag  Indicates  break  status  for  the  current  character: 

$0000  Not  a  word  break  (TextEdit  will  not  extend  the  selection) 

$FFFF  Word  break  (TextEdit  will  extend  the  selection  to  include  next 

word) 
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Custom  scroll  bars 

Your  program  may  specify  a  custom  scroll  bar  for  vertical  scrolling  of  a  TextEdit  record. 
Use  the  vertBar  field  of  the  TEParamBiock  record  to  specify  a  handle  to  the  control 
record  for  the  custom  scroll  bar.  This  scroll  bar  need  not  reside  in  the  TextEdit  record 
display  port,  but  it  must  follow  certain  rules  with  respect  to  the  format  and  content  of  its 
control  record  (see  Chapter  28,  "Control  Manager  Update,"  in  this  book  and 
Chapter  4,  "Control  Manager,"  in  the  Toolbox  Reference  hi  details  on  scroll  bar  controls  and 
control  records): 

■  Fields  corresponding  to  the  datasize,  viewsize,  and  ctivalue  fields  of  a 
standard  scroll  bar  control  record  must  be  located  at  the  same  relative  locations  within 
the  custom  control  record. 

TextEdit  stores  a  handle  to  the  appropriate  TERecord  in  the  ctiRef  con  field  of  the 
scroll  bar  control  record.  Do  not  change  the  contents  of  this  field.  If  you  need  to  store 
additional  information  in  the  scroll  bar  control  record,  extend  the  record  handle  and 
format  that  data  after  the  standard  control  record  fields  (be  sure  to  extract  the  size  of 
the  returned  handle,  rather  than  relying  on  current  record  definitions  for  the  size  of  the 
control  record). 

■  TextEdit  stores  a  pointer  to  its  internal  text  scroll  routine  in  the  ctiAction  field 
ofthe  scroll  bar  control  record  when  the  TextEdit  record  is  created  (during  execution 
of  the  TENew  or  NewControi2  tool  call).  Your  program  may  change  the  contents  of 
this  field,  but  should  save  the  pointer,  so  that  you  can  call  the  TextEdit  text  scroll 
routine  when  appropriate.  For  information  on  the  interface  to  action  routines, 
seeTrack  Control"  in  Chapter  4,  "Control  Manager,"  of  the  Toolbox  Reference. 

Refer  to  Chapter  4,  "Control  Manager,"  for  background  information  on  writing  and 
invoking  control  definition  procedures. 
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TextEdit  data  structures 

This  section  defines  and  discusses  the  various  data  structures  used  by  the  TextEdit  Tool 
Set.  The  TextEdit  data  structures  are  divided  into  high-level  data  structures  and  low-level 
data  structures.  High-level  TextEdit  data  structures  are  of  interest  to  all  application 
programmers  who  use  TextEdit  facilities.  Low-level  TextEdit  data  structures,  on  the  other 
hand,  are  not  relevant  to  most  application  programmers.  However,  if  your  program  uses 
the  low-level  features  of  TextEdit,  or  must  for  some  other  reason  direcdy  access  TextEdit 
data  structures,  you  should  familiarize  yourself  with  the  information  in  that  section. 

In  most  cases,  it  is  not  necessary  for  your  program  to  direcdy  modify  fields  in  these 
structures.  However,  if  your  program  manipulates  TextEdit  structures,  note  that  many  of 
these  data  structures  refer  to  or  depend  upon  one  another.  Whenever  your  application 
changes  one  of  these  structures,  you  must  be  careful  to  update  other  affected  or 
dependent  structures. 
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High-level  TextEdit  structures 

TextEdit  uses  a  number  of  structures  to  store  information  about  a  TextEdit  record  and  to 
pass  that  information  to  TextEdit  tool  calls.  The  following  sections  define  the  format  and 
content  of  each  of  these  structures,  and  describe  how  your  program  would  use  them. 


TEColorTable 

Defines  color  attributes  for  a  TextEdit  record. 

The  TEParamBiock  and  TERecord  contain  references  to  color  tables  stored  in 
TEColorTable  format. 

Note  that  all  bits  in  TextEdit  color  words  (such  as  contentcoior)  are  significant. 
TextEdit  generates  QuickDraw  II  color  patterns  by  replicating  a  color  word  the 
appropriate  number  of  times  for  the  current  resolution  (8  times  for  640  mode,  16  times  for 
320  mode).  See  Chapter  16,  "QuickDraw  II,"  for  more  information  on  QuickDraw  II 
patterns  and  dithered  colors. 
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Figure  49-1      TECoiorTabie  layout 


$00 

—    contentColor    — 

Word 

$02 

—    outlineColor    — 

Word 

$04 

—  hilightForeColor  — 

Word 

$06 

—  hilightBackColor  — 

Word 

$08 

— vertColorDescriptor— 

Word 

$0A 

—    vertColorRef    — 

Long 

$0E 

— horzColorDescriptor— 

Word 

$10 

—    horzColorRef    — 

Long 

$14 

— growColorDescriptor— 

Word 

$16 

—    growColorRef    — 

Long 

contentColor    Defines  the  color  for  the  entire  boundary  rectangle  (in  essence, 
defining  the  background  color  for  the  text  window) 

outlineColor    Defines  the  color  for  box  that  surrounds  the  text  in  the  display 
window. 

hilightForeColor 

Defines  the  foreground  color  for  highlighted  text. 

hilightBackColor 

Defines  the  background  color  for  highlighted  text. 
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vertColorDescriptor 

Defines  the  type  of  reference  stored  in  vertcoiorRef : 

ref  isPointer    $0000     The  vertcoiorRef  field  contains  a  pointer  to  the 

color  table  for  the  vertical  scroll  bar 


reflsHandle 


reflsResource 


$0004     The  vertcoiorRef  field  contains  a  handle  to  the  color 
table  for  the  vertical  scroll  bar 

$0008     The  ve  r t  Co  l  o  r Re  f  field  contains  the  resource  ID  for 
the  color  table  for  the  vertical  scroll  bar 


vertcoiorRef 

Reference  to  the  color  table  for  the  vertical  scroll  bar.  The 

vertColorDescriptor  field  indicates  the  type  of  reference  stored 

here.  This  field  must  refer  to  a  scroll  bar  color  table,  as  defined  in 

Chapter  4,  "Control  Manager,"  of  the  Toolbox  Reference. 

horzColorDescriptor 

Defines  the  type  of  reference  stored  in  horzCoiorRef : 

The  horzCoiorRef  field  contains  a  pointer  to  the 
color  table  for  the  horizontal  scroll  bar 

The  horzCoiorRef  field  contains  a  handle  to  the  color 
table  for  the  horizontal  scroll  bar 

The  horzCoiorRef  field  contains  the  resource  ID  for 
the  color  table  for  the  horizontal  scroll  bar 

Reference  to  the  color  table  for  the  horizontal  scroll  bar. 
horzColorDescriptor  indicates  the  type  of  reference  stored  here.  This 
field  must  refer  to  a  Scroll  bar  color  table,  as  defined  in 
Chapter  4,  "Control  Manager,"  of  the  Toolbox  Reference. 

growColorDescriptor 

Defines  the  type  of  reference  stored  in  growCoiorRef.- 

The  growCoiorRef  field  contains  a  pointer  to  the 
color  table  for  the  size  box 

The  growCoiorRef  field  contains  a  handle  to  the  color 
table  for  the  size  box 

The  growCoiorRef  field  contains  the  resource  ID  for 
the  color  table  for  the  size  box 


reflsPointer 

$0000 

reflsHandle 

$0004 

reflsResource 

$0008 

ho: 

-zColorRef 

Reference  t 

reflsPointer 

$0000 

reflsHandle 

$0004 

reflsResource 

$0008 
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growCoiorRef     Reference  to  the  color  table  for  the  size  box.  The 

growCoiorDescriptor  field  indicates  the  type  of  reference  stored 
here.  This  field  must  refer  to  a  size  box  color  table,  as  defined  in 
Chapter  4,  "Control  Manager,"  of  the  Toolbox  Reference. 
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TEFormat 


This  structure  stores  text  formatting  control  information.  From  this  structure,  you  can 
access  the  rulers  and  styles  defined  for  the  text. 

Many  TextEdit  tool  calls  use  this  structure  to  accept  or  return  format  data  for  a  text 
record. 


Figure  49-2      TEFormat  layout 


$00 
$02 

$06 
$xx 

$xx 
$xx 

$xx 


version 


rulerListLength     -    Long 


Word 


theRuierList         :  Array  ofTERuler  structures 


-     styleListLength     -     Long 


thestyieList         '■  Array  of  TEStyle  structures 


—      numberOfStyles      — 


Long 


thestyies  '•  Array  of  styleltem  structures 


version 


Version  number  corresponding  to  the  layout  of  this  TEFormat 
structure.  This  version  of  the  structure  carries  a  version  number  of 
$0000. 


rulerListLength 

The  length  of  theRuierList  in  bytes. 

theRuierList     Ruler  data  for  the  text  record.  The  TERuier  structure  is  embedded 
within  the  TEFormat  structure  at  this  location. 
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styleList Length 

The  length  of  thestyieList  in  bytes. 

thestyieList     List  of  all  unique  styles  for  the  text  record.  The  TEStyie  structures 
are  embedded  within  the  TEFormat  structure  at  this  location.  Each 
TEStyie  structure  must  define  a  unique  style— there  must  be  no 
duplicate  style  entries.  In  order  to  apply  the  same  style  to  multiple 
blocks  of  text,  you  should  create  additional  styieitems  for  each 
block  of  text,  and  make  each  item  refer  to  the  same  style  in  this  array. 

numberOf Styles 

The  number  of  styieitems  contained  in  thestyies. 

thestyies  Array  of  styieitems  specifying  which  actual  styles  (stored  in 

thestyieList)  apply  to  which  text  within  the  TextEdit  record. 
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TEParamBlock 

This  structure  contains  the  parameters  necessary  to  create  a  new  TextEdit  record.  In  it 
your  program  defines  many  of  the  attributes  of  the  record.  The  format  of  this  structure 
direcdy  corresponds  to  the  format  of  the  TextEdit  control  template  accepted  by  the 
NewControi2  Control  Manager  call  when  creating  TextEdit  controls. 

The  TENew  tool  call  requires  that  its  input  parameters  be  specified  in  a  TEParamBlock 
structure.  Many  of  the  fields  of  the  TEParamBlock  direcdy  establish  the  values  for 
TERecord  fields. 

In  the  following  figure,  optional  fields  are  marked  with  an  asterisk  (*). 
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Figure  49-3      TEParamBiock  layout 


$00 
$02 

$06 
$0E 

$12 
$14 
$16 

$1A 

$1E 
$26 

$2A 
$2C 

$30 


pCount 


Word— Parameter  count  for  template:  7  to  23 


id  -   Long— Application-assigned  control  ID 

rect  \  Rectangle— Boundary  rectangle  for  control 


—  moreFlags 


procRef  -    Long— editTextControl=$85000000 


flag 


re t Con 


textFlags 


Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 

Long— Specific  TextEdit  control  flags  (see  below) 


*indentRect         \  Rectangle— Defines  text  indentation  from  control  rect  (optional) 


—  *vertAmount  — 


•horzBar 


*horzAmount 


continued 


Long— Handle  to  vertical  scroll  bar  for  control  (optional) 
Word— Vertical  scroll  amount,  in  pixels  (optional) 
Long— Reserved;  must  be  set  to  Mil  (optional) 
Word— Reserved;  must  be  set  to  0  (optional) 
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continued 

$32 

— 

*styleRef 

- 

*"" 

$36 

* text Descriptor 

- 

$38 

_ 

* text Re f 

- 

— 

$3C 

_ 

*text Length 

- 

— 

$40 

— 

*maxChars 

- 

— 

$44 

— 

♦maxLines 

- 

— 

$48 

*maxCharsPerLines 

- 

$4A 

*maxHeight 

- 

$4C 

— 

*colorRef 

- 

— 

$50 

*drawMode 

- 

$52 

— 

*filterProcPtr 

- 

— 

-  Long— Reference  to  initial  style  information  for  text  (optional) 

-  Word— Defines  format  of  initial  text  and  textRef  (optional) 

-  Long— Reference  to  initial  text  for  edit  window  (optional) 

Long— Length  of  initial  text  (optional) 

-  Long— Maximum  number  of  characters  allowed  (optional) 

-  Long— Reserved;  must  be  set  to  0  (optional) 

Word— Reserved;  must  be  set  to  0  (optional) 
Word— Reserved;  must  be  set  to  0  (optional) 

-  Long— Reference  to  TextEdit  color  table  (optional) 
Word— QuickDraw  II  text  mode  for  edit  window  (optional) 
Long— Pointer  to  filter  routine  for  this  control  (optional) 


pCount 


ID 


Number  of  parameter  fields  to  follow.  Valid  values  lie  in  the  range  from 
7  to  23.  The  value  of  this  field  does  not  include  pCount  itself. 

Unique  ID  for  TextEdit  controls.  Your  application  sets  this  field,  and 
can  use  it  to  uniquely  identify  a  particular  TextEdit  record. 
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boundsRect         Boundary  rectangle  for  the  TextEdit  record.  This  rectangle  contains 
the  entire  record,  including  its  scroll  bars  and  outline.  If  you  set  the 
bottom  right  corner  of  this  rectangle  to  (0,0),  TextEdit  uses  the 
bottom  right  corner  of  the  window  that  contains  the  record  as  a 
default.  Note  that  this  rectangle  must  be  large  enough  to  completely 
display  a  single  character  in  the  largest  allowed  font. 

procRef  Specifies  the  type  of  control.  Must  be  set  to  $85000000. 

flag  Control  flags  for  the  TextEdit  record.  Defined  bits  for  flag  are  as 

follows: 

Reserved  bits  8-15     Must  be  set  to  0 

ctiinvis  bit  7  l=invisible,  0=visible 

Reserved  bits  0-6      Must  be  set  to  0 
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moreFiags  More  control  flags  for  TextEdit  record.  Defined  bits  for  moreFiags 

are  as  follows: 

f  ctiTarget  bit  15         Indicates  whether  this  TextEdit  record  is  the  current 

target  of  user  actions.  Must  be  set  to  0  when  creating 
a  TextEdit  record. 

Must  be  set  to  1.  TextEdit  will  set  this  bit  to  0  if  the 
fDisableSelection  flag  in  textFlags   is  set 

tol. 

Must  be  set  to  1.  TextEdit  will  set  this  bit  to  0  if  the 

fDisableSelection  flag  in  textFlags   is  set 

tol. 

Must  be  set  to  1 

If  set  to  1,  TextEdit  will  create  a  size  box  in  the 

bottom  right  corner  of  the  window.  Whenever  the 

window  is  resized,  the  edit  text  will  be  resized  and 

redrawn. 

Must  be  set  to  1 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorRef : 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 
10  -  color  table  reference  is  resource  ID 
11 -invalid  value 

bits  0-1       Defines  type  of  style  reference  in  styieRef : 

00  -  style  reference  is  pointer 

01  -  style  reference  is  handle 
10  -  style  reference  is  resource  ID 
11 -invalid  value 


fCtlCanBeTarget      bit  14 


fCtlWantsEvents      bit  13 


fCtlProcNotPtr        bit  12 
fTellAboutSize        bit  11 


fCtllsMultiPart      bit  10 
Reserved  bits  4-9 

Color  Table  Reference  bits  2-3 


Style  Reference 


A  Important 


Do  not  set  f  TeiiAboutsize  to  1  unless  the  window  also  has  a 
vertical  scroll  bar.  a 
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textFlags 


fNotControl 


f SingleFormat 
fSingleStyle 


fNoWordWrap 


fNoScroll 


fReadOnly 


Specific  TextEdit  control  flags.  Valid  values  for  textFlags  are  as 
follows: 


bit  31 


bit  30 
bit  29 


bit  28 


bit  27 


bit  26 


f SmartCutPaste 


fTabSwitch 


fDrawBounds 


bit  25 


bit  24 


bit  23 


fColorHilight 
fGrowRuler 


bit  22 
bit  21 


Indicates  whether  the  the  TextEdit  record  to  be 

created  is  for  a  control: 

1  -  TextEdit  record  is  not  a  control 

0  -  TextEdit  record  is  a  control 
Must  be  set  to  1 

Allows  you  to  restrict  the  style  options  available  to 
the  user: 

1  -  Allow  only  one  style  in  the  text 

0  -  Do  not  restrict  the  number  of  styles  in  the  text 
Allows  you  to  control  TextEdit  word  wrap  behavior: 

1  -  Do  not  word  wrap  the  text;  only  break  lines  on  CR 
($0D)  characters 

0  -  Perform  word  wrap  to  fit  the  ruler 
Controls  user  access  to  scrolling: 

1  -  Do  not  allow  either  manual  or  auto-scrolling 

0  -  Scrolling  permitted 

Restricts  the  text  in  the  window  to  read-only 
operations  (copying  from  the  window  will  still  be 
allowed): 

1  -  No  editing  allowed 

0  -  Editing  permitted 

Controls  TextEdit  support  for  smart  cut  and  paste: 

1  -  Use  smart  cut  and  paste 

0  -  Do  not  use  smart  cut  and  paste 
Defines  behavior  of  the  Tab  key: 

1  -  Tab  to  next  control  in  the  window 

0  -  Tab  inserted  in  TextEdit  document 

Tells  TextEdit  whether  to  draw  a  box  around  the  edit 
window,  just  inside  boundsRect— the  pen  for  this 
box  is  two  pixels  wide  and  one  pixel  high 

1  -  Draw  rectangle 

0  -  Do  not  draw  rectangle 
Must  be  set  to  0. 

Tells  TextEdit  whether  to  resize  the  ruler  in  response 
to  the  user  resizing  the  edit  window.  If  set  to  1, 
TextEdit  will  automatically  adjust  the  right  margin 
value  for  the  ruler: 

1  -  Resize  the  ruler 

0  -  Do  not  resize  the  ruler 
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fDrawInactiveSelection 
bit  19 


fDi sable Select ion 

bit  20         Controls  whether  user  can  select  text: 
1  -  User  cannot  select  text 

0  -  User  can  select  text 

Controls  how  inactive  selected  text  is  displayed: 

1  -  TextEdit  draws  a  box  around  inactive  selections 
0  -  TextEdit  does  nothing  special  when  displaying 
inactive  selections 

Reserved  bits  0-18     Must  be  set  to  0 

indentRect        Each  coordinate  of  this  rectangle  specifies  the  amount  of  white  space 
to  leave  between  the  boundary  rectangle  for  the  control  and  the  text 
itself,  in  pixels.  Default  values  are  (2,6,2,4)  in  640  mode  and  (2,4,2,2) 
in  320  mode.  Each  indentation  coordinate  may  be  specified 
individually.  In  order  to  assert  the  default  for  any  coordinate,  specify 
its  value  as  $FFFF. 

vertBar  Handle  of  the  vertical  scroll  bar  to  use  for  the  TextEdit  window.  If  you 

do  not  want  a  scroll  bar  at  all,  then  set  this  field  to  NIL.  If  you  want 
TextEdit  to  create  a  scroll  bar  for  you,  just  inside  the  right  edge  of  the 
boundary  rectangle  for  the  control,  then  set  this  field  to  $FFFFFFFF. 

vert  Amount  Specifies  the  number  of  pixels  to  scroll  whenever  the  user  presses  the 
up  or  down  arrow  on  the  vertical  scroll  bar.  In  order  to  use  the  default 
value  (9  pixels),  set  this  field  to  $0000. 

horzBar  Must  be  set  to  NIL. 

horzAmount  Must  be  set  to  0. 

styieRef  Reference  to  initial  style  information  for  the  text,  specified  in  a 

TEFormat  structure.  Bits  1  and  0  of  moreFiags  define  the  type  of 
reference  (pointer,  handle,  resource  ID)  to  the  structure.  In  order  to 
use  the  default  style  and  ruler  information,  set  this  field  to  NULL. 


textDescriptor 

Input  text  descriptor  that  defines  the  reference  type  for  the  initial 
text  (which  is  in  textRef )  and  the  format  of  that  text. 

textRef  Reference  to  initial  text  for  the  edit  window.  If  you  are  not  supplying 

any  initial  text,  then  set  this  field  to  NULL. 

textLength        If  textRef  is  a  pointer  to  the  initial  text,  then  this  field  must  contain 
the  length  of  the  initial  text.  For  other  reference  types,  this  field  is 
ignored— TextEdit  can  extract  the  length  from  the  reference  itself. 
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♦    Note:  YOU  must  specify  or  omit  the  textDescriptor,  textRef,  andtextLength 
fields  as  a  group. 


maxChars 


maxLines 


Maximum  number  of  characters  allowed  in  the  text.  If  you  do  not  want 
to  define  any  limit  to  the  number  of  characters,  then  set  this  field  to 
NULL. 

Must  be  set  to  NULL. 


maxCharsPerLines 

Must  be  set  to  NULL. 

maxHeight  Must  be  set  to  NULL. 

coiorRef  Reference  to  the  color  table  for  the  text,  stored  in  a  TECoiorTabie 

structure.  Bits  2  and  3  of  moreFiags  define  the  type  of  reference 
stored  here. 

drawMode  This  is  the  text  mode  used  by  QuickDraw  II  for  drawing  text.  See 

Chapter  16,  "QuickDraw  II,"  in  Volume  2  of  the  Toolbox  Reference  for 
details  on  valid  text  modes. 

f  iiterProcPtr  Pointer  to  a  filter  routine  for  the  control.For  more  information  about 
TextEdit  filter  procedures,  see  "Generic  filter  procedure".  If  you  do 
not  want  to  use  a  filter  routine  for  the  control,  set  this  field  to  NIL. 
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TERuler 

Defines  the  characteristics  of  a  TextEdit  ruler. 

The  TEGetRuier  and  TESetRuier  tool  calls  allowyou  to  obtain  and  set  the  ruler 
information  for  a  TextEdit  record. 

■    Figure  494      TERuler  layout 
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leftlndent 
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$04 

rightMargin 

- 

$06 

just 

- 

$08 

extraLS 

- 

$0A 

flags 

- 

$0E 

userData 

- 

$12 

tabType 

- 

$14 

Word 
Word 
Word 
Word 
Word 
Word 

-   Long 
Word 
theTabs  :  Array  of  Tab  It  em  structures 


'X*    -       tabTerminator       -    Word 


leftMargin 


leftlndent 


rightMargin 


Specifies  the  number  of  pixels  to  indent  from  the  left  edge  of  the  text 
rectangle  (viewRect  in  TERecord)  for  all  text  lines  except  those 
that  start  paragraphs. 

Specifies  the  number  of  pixels  to  indent  from  the  left  edge  of  the  text 
rectangle  (viewRect  in  TERecord)  for  text  lines  that  start 
paragraphs. 

Maximum  line  length,  expressed  as  the  number  of  pixels  from  the  left 
edge  of  the  text  rectangle  (viewRect  in  TERecord). 
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just  Text  justification: 

0  Left  justification— all  text  lines  start  flush  with  left  margin 
-1  Right  justification — all  text  lines  start  flush  with  right  margin 

1  Center  justification— all  text  lines  are  centered  between  left  and 
right  margins 

2  Full  justification — text  is  blocked  flush  with  both  left  and  right 
margins;  TextEdit  pads  spaces  with  extra  pixels  to  fully  justify 
the  text 

extraLS  Line  spacing,  expressed  as  the  number  of  pixels  to  add  between  lines 

of  text.  Negative  values  result  in  text  overlap. 

flags  Control  flags: 


Reserved                    bit  15 

Must  be  set  to  0 

f Equal Line Spacing 

bit  14 

Must  be  set  to  0 

f  Showlnvisibles      bit  13 

Must  be  set  to  0 

Reserved                    bits  0-12 

Must  be  set  to  0 

userData  Application-specific  data. 

tabType  Specifies  the  type  of  tab  data  that  follows: 

0  No  tabs  are  set— tabType  is  the  last  field  in  the  structure 

1  Regular  tabs— tabs  are  set  at  regular  pixel  intervals,  specified  by 
the  value  Of  the  tabTerminator  field;  theTabs  is  omitted 
from  the  structure 

2  Absolute  tabs— tabs  are  set  at  absolute,  irregular  pixel  locations; 
theTabs  defines  those  locations;  tabTerminator  marks  the 
end  of theTabs 

theTabs  If  tabType  is  set  to  2,  then  this  is  an  array  of  Tabitem  structures 

defining  the  absolute  pixel  positions  for  the  various  tab  stops.  The 
tabTerminator  field,  with  a  value  of  $FFFF,  marks  the  end  of  this 
array.  For  other  values  of  tabType,  this  field  is  omitted  from  the 
structure. 

tabTerminator  If  tabType  is  set  to  0,  then  this  field  is  omitted  from  the  structure.  If 
tabType  is  set  to  1,  then  theTabs  is  omitted,  and  this  field  contains 
the  number  of  pixels  corresponding  to  the  tab  interval  for  the  regular 
tabs.  If  tabType  is  set  to  2,  then  tabTerminator  is  set  to  $FFFF, 
and  marks  the  end  of  theTabs  array. 
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TEStyle 

This  structure  defines  the  font  and  color  characteristics  of  a  style  for  text  in  the  TextEdit 
record. 

The  TEFormat  structure  contains  one  or  more  TEStyle  structures,  each  of  which  defines 
a  unique  text  style  used  somewhere  in  the  record  text. 


Figure  49-5      TEStyle  layout 
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—     foreColor     — 
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—     userData     — 

Long 

Word 
Word 
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font  id  Font  Manager  font  ID  record  identifying  the  font  for  the  text.  See 

Chapter  8,  "Font  Manager,"  in  the  Toolbox  Reference  for  more 
information  about  font  IDs. 

foreColor  Defines  the  foreground  color  for  the  text.  This  is  a  TextEdit  color 

word,  as  described  in  "TECoiorTabie"  in  this  chapter. 

backColor  Defines  the  background  color  for  the  text.  This  is  a  TextEdit  color 

word,  as  described  in  "TECoiorTabie"  in  this  chapter. 

userData  Application-specific  data. 
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Low-level  TextEdit  structures 

TextEdit  uses  several  other  structures  for  its  internal  processing.  Typically,  your 
application  should  not  manipulate  these  structures.  In  addition,  if  your  program  does 
modify  data  in  these  structurers,  you  should  be  careful  to  maintain  the  correct 
relationships  between  fields  that  affect  other  TextEdit  structures. 

TERecord 

This  is  the  main  structure  for  a  TextEdit  record.  The  TENew  tool  call  creates  this  structure 
based  partially  on  the  information  specified  in  the  TEParamBiock  you  supply  to  that 
call.  In  most  cases,  your  program  does  not  need  to  direcdy  access  fields  in  this  structure. 
However,  in  order  to  use  such  advanced  features  as  custom  word-wrap  routines,  your 
application  will  have  to  modify  the  TERecord. 

Note  that  this  section  only  describes  those  TERecord  fields  that  are  currently  defined 
and  available  to  application  programs.  Your  program  should  assume  that  there  are  more 
fields  beyond  those  described  here,  and  should  not  try  to  directly  move  or  copy  a 
TERecord. 

Most  TextEdit  tool  calls  require  a  handle  to  a  TERecord  as  an  entry  parameter. 
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Figure  49-6      TERecord  layout 
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$76 
$78 
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—      selectionState      — 


$7E 
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continued 


selectionActive     — 


—  caretTime 


—     nullStyleActive     — 
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nullStyle  '■    TEStyle 
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—   vertScrollPos   —  Long 
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—   vertScrollMax   —  Long 


—  vertScrollAmount  —  Word 


—   horzScrollBar   —  Long 


—   horzScrollPos   —  Long 


continued 
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continued 
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ouseRect  :  Rectangle 
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—  anchorPoint         — |    Long 


—  savedHPos  — 


ctrlNext 

inPort 

boundsRect 

ctrlFlag 


ctllnvis 
Reserved 


Handle  of  next  control  in  the  system-maintained  control  list. 

Pointer  to  the  GrafPort  for  this  TextEdit  record. 

Boundary  rectangle  for  the  record,  which  surrounds  the  text  window  as 
well  as  its  scroll  bars  and  outline. 

Control  flags  for  the  TextEdit  record.  TextEdit  obtains  this  field  from 
the  low-order  byte  of  the  flags  field  in  the  TEParamBiock  passed 
to  TENew.  The  following  flags  are  defined: 

bit  7  l=invisible,  0=visible 

bits  0-6      Must  be  set  to  0 
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ctrlHilite 


Reserved 


lastErrorCode  The  last  error  code  generated  by  TextEdit.  Note  that  this  code  may 
have  been  returned  by  either  a  control  definition  procedure  or  from  a 
TextEdit  tool  call. 


ctrlProc 

ctrlAction 
filterProc 

ctrlRefCon 
colorRef 

textFlags 


Must  be  set  to  $85000000.  Identifies  this  as  a  TextEdit  control  to  the 
system. 

Reserved 

Pointer  to  the  generic  filter  procedure  for  the  record.  If  there  is  no 
filter  procedure,  this  field  is  set  to  NULL.  See  "Generic  filter 
procedure"  for  information  about  generic  filter  procedures. 

Application-defined  value. 

Reference  to  the  TECoiorTabie  for  the  record.  Bits  2  and  3  in 
ctriMoreFiags  define  the  type  of  reference  stored  here. 

Control  flags  specific  to  TextEdit.  The  system  derives  this  field  from 
the  textFlags  field  in  the  TEParamTabie  structure  passed  to 
TENew  when  a  new  TextEdit  record  is  created.  The  following  flags  are 
defined: 


fNotControl 


fSingleFormat 
fSingleStyle 


fNoWordWrap 


fNoScroll 


bit  31 


bit  30 
bit  29 


bit  28 


bit  27 


Indicates  whether  the  the  TextEdit  record  to  be 

created  is  for  a  control: 

1  -  TextEdit  record  is  not  a  control 

0  -  TextEdit  record  is  a  control 
Must  be  set  to  1 

Allows  you  to  restrict  the  style  options  available  to 
the  user: 

1  -  Allow  only  one  style  in  the  text 

0  -  Do  not  restrict  the  number  of  styles  in  the  text 
Allows  you  to  control  TextEdit  word  wrap  behavior: 

1  -  Do  not  word  wrap  the  text;  only  break  lines  on  CR 
($0D)  characters 

0  -  Perform  word  wrap  to  fit  the  ruler 
Controls  user  access  to  scrolling: 

1  -  Do  not  allow  either  manual  or  auto-scrolling 
0  -  Scrolling  permitted 
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fReadOnly 


f  SmartCutPaste        bit  25 


fTabSwitch 


fDrawBounds 


f  ColorHilight  bit  22 

fGrowRuler  bit  21 


bit  26  Restricts  the  text  in  the  window  to  read-only 

operations  (copying  from  the  window  will  still  be 

allowed): 

1  -  No  editing  allowed 

0  -  Editing  permitted 
Controls  TextEdit  support  for  smart  cut  and  paste: 

1  -  Use  smart  cut  and  paste 

0  -  Do  not  use  smart  cut  and  paste 
bit  24         Defines  behavior  of  the  Tab  key: 

1  -  Tab  to  next  control  in  the  window 

0  -  Tab  inserted  in  TextEdit  document 

bit  23         Tells  TextEdit  whether  to  draw  a  box  around  the  edit 
window,  just  inside  boundsRect.  The  pen  for  this 
rectangle  is  two  pixels  wide  and  one  pixel  high 

1  -  Draw  rectangle 

0  -  Do  not  draw  rectangle 
Must  be  set  to  0. 

Tells  TextEdit  whether  to  resize  the  ruler  in  response 
to  the  user  resizing  the  edit  window.  If  set  to  1, 
TextEdit  will  automatically  adjust  the  right  margin 
value  for  the  ruler: 

1  -  Resize  the  ruler 
0  -  Do  not  resize  the  ruler 


fDrawInactiveSelection 

bit  19 


fDisableSelection 

bit  20         Controls  whether  user  can  select  text: 
1  -  User  cannot  select  text 

0  -  User  can  select  text 

Controls  how  inactive  selected  text  is  displayed: 

1  -  TextEdit  draws  a  box  around  inactive  selections 
0  -  TextEdit  does  not  display  inactive  selections 

Reserved  bits  0-18     Must  be  set  to  0 

textLength        Number  of  bytes  of  text  in  the  record.  Your  program  must  not  modify 
this  field. 

biockList  Cached  link  into  the  linked  list  of  TextBiock.  structures,  which 

contain  the  actual  text  for  the  record.  The  actual  Text  List  structure 
resides  here.  Your  program  must  not  modify  this  field. 

ctri  id  Application-assigned  ID  for  the  TextEdit  control. 


49-54    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  11GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


ctriMoreFiags  More  control  flags.  TextEdit  obtains  the  data  for  this  field  from  the 
moreFlags  field  of  the  TEParamBlock  Structure  passed  to  TENew 
when  a  new  TextEdit  record  is  created.  The  following  flags  are 
defined: 


fCtlTarget 


bit  15 


fCtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 

fTellAboutSize  bit  11 


fCtllsMultiPart      bit  10 
Reserved  bits  4-9 

Color  Table  Reference  bits  2-3 


Reserved 

ctrlVersion 
viewRect 


totalHeight 
lineSuper 

styleSuper 

styleList 

rulerList 


bits  0-1 
Reserved 


Indicates  whether  this  TextEdit  record  is  the  current 

target  of  user  actions.  Must  be  set  to  0  when  creating 

a  TextEdit  record. 

Must  be  set  to  1 

Must  be  set  to  1. 

Must  be  set  to  1 

If  set  to  1,  TextEdit  will  create  a  size  box  in  the 

bottom  right  corner  of  the  window.  Whenever  the 

window  is  resized,  the  edit  text  will  be  resized  and 

redrawn. 

Must  be  set  to  1 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorRef : 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 
11 -invalid  value 
Must  be  set  to  0 


Boundary  rectangle  for  the  text,  within  the  rectangle  defined  in 
boundsRect,  which  surrounds  the  entire  record,  including  its 
associated  scroll  bars  and  outline. 

Total  height  of  the  text  in  the  TextEdit  record,  in  pixels. 

Cached  link  into  the  linked  list  of  superBiock  structures  that  define 
the  text  lines  in  the  record. 

Cached  link  into  the  linked  list  of  SuperBiock  structures  that  define 
the  styles  for  the  record. 

Handle  to  array  of  TEStyle  structures,  containing  style  information 
for  the  record.  The  array  is  terminated  with  a  long  set  to  $FFFFFFFF. 

Handle  to  array  of  TERuier  structures,  defining  the  format  rulers  for 
the  record.  Note  that  only  the  first  ruler  is  currently  used  by  TextEdit. 
The  array  is  terminated  with  a  long  set  to  $FFFFFFFF. 
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UneAtEndFiag  Indicates  whether  the  last  character  was  a  line  break.  If  so,  this  field  is 
set  to  $FFFF. 

selections tart 

Starting  text  offset  for  the  current  selection.  Must  always  be  less  than 

selectionEnd. 

seiectionEnd    Ending  text  offset  for  the  current  selection.Must  always  be  greater 
than  selectionStart. 

selectionActive 

Indicates  whether  the  current  selection  (defined  by 
selectionStart  and  selectionEnd)  is  active: 


$0000 

Active 

$FFFF 

Inactive 

select ionSt ate 

Contains  st 

$0000 

Off  screen 

$FFFF 

On  screen 

Contains  state  information  about  the  current  selection  range: 


caretTime  Blink  interrval  for  caret,  expressed  in  system  ticks. 

nullStyleActive 

Indicates  whether  the  null  style  is  active  for  the  current  selection: 

$0000  Do  not  use  null  style  when  inserting  text 

$FFFF  Use  null  style  when  inserting  text 

nuiistyle  TEStyle  structure  defining  the  null  style.  This  may  be  the  default 

style  for  newly  inserted  text,  depending  upon  the  value  of 

nullStyleActive. 

topTextof  f  set  Text  offset  into  the  record  corresponding  to  the  top  line  displayed  on 
the  screen. 

topTextvPos      Difference,in  pixels,  between  the  topmost  vertical  scroll  position 
(corresponding  to  the  top  of  the  vertical  scroll  bar)  and  the  top  line 
currently  displayed  on  the  screen.  This  is,  essentially,  the  vertical 
position  of  the  display  window  in  the  text  for  the  record. 

vertScroiiBar  Handle  to  the  vertical  scroll  bar  control  record. 

vertScroiiPos  Current  position  of  the  vertical  scroll  bar,  in  units  defined  by 
ve  rt  S  c  r ol lAmount . 
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♦   Note:  that  while  TextEdit  supports  vertscroiiPos  as  a  long,  standard  Apple  IIGS 
scroll  bars  support  only  the  low-order  word.  This  leads  to  unpredictable  scroll  bar 
behavior  when  editing  large  documents. 

vertscroiiMax  Maximum  allowable  vertical  scroll,  in  units  defined  by 

vertScrollAmount. 

vertScrollAmount 

Number  of  pixels  to  scroll  on  each  vertical  arrow  click. 

horzScroiiBar  Handle  to  the  horizontal  scroll  bar  control  record.  Currently  not 
supported 

horzScroiiPos  Current  position  of  the  horizontal  scroll  bar,  in  units  defined  by 
horzScroiiAmount.  Currently  not  supported 

horzScroiiMax  Maximum  allowable  horizontal  scroll,  in  units  defined  by 
horzScroiiAmount.  Currently  not  supported 

horzScroiiAmount 

Number  of  pixels  to  scroll  on  each  horizontal  arrow  click.  Currently  not 
supported. 

growBoxHandie  Handle  of  size  box  control  record. 

maximumchars     Maximum  number  of  characters  allowed  in  the  text. 

maximumLines     Maximum  number  of  lines  allowed  in  the  text.  Currently  not  supported. 

maxCharsPerLine 

Currently  not  supported. 

maximumHeight  Maximum  text  height,  in  pixels.  This  value  allows  applications  to  easily 
constrain  text  to  a  display  window  of  a  known  height.  Currently  not 
supported. 

textDrawMode    QuickDraw  II  drawing  mode  for  the  text.  See 

Chapter  16,  "QuickDraw  II,"  in  the  Toolbox  Reference  for  more 
information  on  QuickDraw  II  drawing  modes. 

wordBreakHook  Pointer  to  the  routine  that  handles  word  breaks.  See  "Word  break 
hook"  earlier  in  this  chapter  for  information  about  word  break 
routines.  Your  program  may  modify  this  field. 
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wordwrapHook  Pointer  to  the  routine  that  handles  word  wrap.  See  "Word  wrap  hook" 
earlier  in  this  chapter  for  information  about  word  wrap  routines.  Your 
program  may  modify  this  field. 

keyFiiter  Pointer  to  the  keystroke  filter  routine.  See  "Keystroke  filter 

procedure"  earlier  in  this  chapter  for  information  about  keystroke 
filter  routines.  Your  program  may  modify  this  field. 

theFiiterRect  Defines  a  rectangle  used  by  the  generic  filter  procedure  for  some  of  its 
routines.  See  "Generic  filter  procedure"  earlier  in  this  chapter  for 
information  about  generic  filter  procedures  and  their  routines.  Your 
program  may  modify  this  field. 

theBuf  f  erVPos  Vertical  component  of  the  current  position  of  the  buffer  within  the 
port  for  the  TextEdit  record,  expressed  in  the  local  coordinates 
appropriate  for  that  port.  This  value  is  used  by  some  generic  filter 
procedure  routines.  See  "Generic  filter  procedure"  for  information 
about  generic  filter  procedures  and  their  routines.  Your  program  may 
modify  this  field. 

theBuf  ferHPos  Horizontal  component  of  the  current  position  of  the  buffer  within  the 
port  for  the  TextEdit  record,  expressed  in  the  local  coordinates 
appropriate  for  that  port.  This  value  is  used  by  some  generic  filter 
procedure  routines.  See  "Generic  filter  procedure"  earlier  in  this 
chapter  for  information  about  generic  filter  procedures  and  their 
routines.  Your  program  may  modify  this  field. 

theKeyRecord    Parameter  block,  in  KeyRecord  format,  for  the  keystroke  filter 
routine.  Your  program  may  modify  this  field. 

cachedSelcOf f set 

Cached  selection  text  offset.  If  this  field  is  set  to  $FFFFFFFF,  then  the 
cache  is  invalid  and  will  be  recalculated  when  appropriate. 

cachedSelcVPos 

Vertical  component  of  the  cached  buffer  position,  expressed  in  local 
coordinates  for  the  output  port. 

cachedSelcHPos 

Horizontal  component  of  the  cached  buffer  position,  expressed  in 
local  coordinates  for  the  output  port. 
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mouseRect 


mouseTime 

mouseKind 

0 
1 
2 

lastClick 

savedHPos 

anchorPoint 


Boundary  rectangle  for  multiclick  mouse  commands.  If  the  user  clicks 
the  mouse  more  than  once  within  the  region  defined  by  this  rectangle 
within  the  time  period  defined  for  multiclicks,  then  TextEdit 
interprets  those  clicks  as  multiclick  sequences  (double-  or  triple- 
clicks).  The  user  sets  the  time  period  with  the  Control  Panel. 

System  tickcount  when  the  user  last  released  the  mouse  button. 

Type  of  last  mouse  click: 

Single  click 

Double-click 

Triple-click 

Location  of  last  user  mouse  click. 

Cached  horizontal  character  position.  TextEdit  uses  this  value  to 
manage  where  it  should  display  the  caret  on  a  line  when  the  user 
presses  the  up  or  down  arrow. 

Defines  the  character  from  which  the  user  began  to  select  text  for  the 
current  selection.  When  TextEdit  expands  the  current  selection  (as  a 
result  of  user  keyboard  or  mouse  commands,  or  at  the  direction  of  a 
custom  keystroke  filter  procedure),  it  always  does  so  from  the 
anchorPoint,  not  selectionStart  or  selectionEnd. 


KeyRecord 

Defines  the  entry  and  exit  parameter  block  for  the  keystroke  filter  procedure  for  a 
TextEdit  record.  On  entry  to  the  filter  procedure,  TextEdit  sets  up  this  structure  with  the 
information  necessary  to  process  the  keystroke.  On  exit,  the  filter  procedure  returns  the 
processed  keystroke  and  any  other  status  information  in  this  same  structure.  For 
complete  information  about  the  TextEdit  keystroke  filter  procedure  and  the  use  of  these 
fields,  see  "Keystroke  filter  procedure"  earlier  in  this  chapter. 

The  KeyRecord  for  a  TextEdit  record  resides  in  the  appropriate  TERecord. 
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Figure  49-7      Key  Re  c  o  r  d  layout 
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Character  code  of  the  character  to  translate.  The  low-order  byte  of 
thechar.contains  the  key  code  for  the  character;  the  high-order  byte 
is  ignored. 

On  input,  contains  the  state  of  the  modifier  keys  when  the  character 
in  theChar  was  generated.  This  is  an  Event  Manager  modifier  word, 
as  described  in  Chapter  7,  "Event  Manager,"  of  the  Toolbox  Reference. 
On  output,  the  keystroke  filter  procedure  may  change  the  setting  of 
these  flags. 


thelnputHandle 

On  input,  contains  a  handle  to  a  copy  of  the  keystroke  in  theChar. 
On  output,  the  keystroke  filter  procedure  may  modify  the  size  and 
content  of  the  data  referred  to  by  this  handle. 

cursorOffset    For  some  operations,  the  keystroke  filter  routine  sets  this  field  with  a 
new  cursor  text  offset. 
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theOpCode 


opNormal 


opNothing 
opReplaceText 


On  return  from  the  filter  routine,  this  field  contains  an  operation  code 
indicating  what  TextEdit  is  to  do  next  and  how  it  is  to  interpret  the 
KeyRecord: 


$0000 


$0001 
$0002 


opMoveCursor 

$0003 

opExtendCursor 

$0004 

opCut 

$0005 

opCopy 

$0006 

opPaste 

$0007 

opClear 

$0008 

TextEdit  performs  its  standard  processing  on  the 
character  stored  in  the  location  referred  to  by 

thelnputHandle 

TextEdit  ignores  the  keystroke 

TextEdit  inserts  the  text  referred  to  by 

thelnputHandle  in  place  of  the  current  selection 

in  the  record;  if  there  is  no  current  selection,  TextEdit 

inserts  the  text  at  the  current  insertion  point— if 

thelnputHandle  has  0  size,  TextEdit  deletes  the 

current  selection  and  inserts  nothing 

TextEdit  moves  the  cursor  to  the  location  specified 

by  cursorOf f set 

TextEdit  extends  the  current  selection  from  its 

anchor  point  to  the  location  specified  by 

cursorOf f set 

TextEdit  copies  the  current  selection  to  the  desk 

scrap  then  clears  the  selection 

TextEdit  copies  the  current  selection  to  the  desk 

scrap 

TextEdit  inserts  the  contents  of  the  desk  scrap  in 

place  of  the  current  selection 

TextEdit  clears  the  current  selection 
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Styleltem 

The  TEFormat  structure  contains  an  array  of  styleltem  substructures,  which  define  the 
text  characters  that  use  a  particular  style.  Each  element  of  this  array  refers  to  the  style 
information  for  a  run  of  characters.  Taken  consecutively,  the  array  of  styleltem 
structures  completely  defines  the  styles  for  the  entire  record. 


Figure  49-8      style  it  em  layout 
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offset 


The  total  number  of  text  characters  that  use  this  style.  These 
characters  begin  where  the  previous  styleltem  left  off.  Value  of 
$FFFFFFFF  indicates  an  unused  entry. 

Offset,  in  bytes,  into  theStyieList  array  in  the  TEFormat  record 
to  the  TEStyle  record  which  defines  the  characteristics  of  the  style 
in  question. 
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SuperBlock 

SuperBiock  structures  define  linked-lists  of  TextEdit  control  information  items.  These 
control  information  items  may  relate  to  styles  or  to  line  start  locations,  and  are  defined  by 
the  Superitem  substructure.  A  superHandie  substructure  provides  address 
information  into  a  chain  of  SuperBlock  structures.  The  TERecord  contains  a  number 
of  SuperHandles. 


Figure  49-9      SuperBlock  layout 
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nextHandle        Handle  to  the  next  SuperBlock  in  this  chain  of  blocks.  A  value  of 
NIL  indicates  the  end  of  the  chain. 

prevHandle        Handle  to  the  previous  SuperBlock  in  this  chain  of  blocks.  A  value 
of  NIL  indicates  the  beginning  of  the  chain. 

textLength        The  number  of  characters  of  text  referred  to  by  theltems . 

Reserved  Reserved 

theltems  Array  of  Superltems  for  this  SuperBlock.  The  textLength  field 

contains  the  total  length  of  the  characters  defined  by  these  items. 
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SuperHandle 

Identifies  the  current  position  within  a  chain  of  SuperBiocks.  This  substructure 
contains  both  byte  offset  and  index  information.  The  cachedof  f  set  field  contains  the 
offset  into  the  text  identified  by  the  cached  supentem.  The  cachedindex  field 
contains  the  byte  offset  to  the  Superitem  within  its  SuperBiock.  The  TERecord 
contains  several  SuperHandies. 


Figure  49-10     SuperHandle  layout 
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cachedHandle     Handle  to  the  SuperBiock  containing  the  current  Superitem. 

cachedOffset     Byte  offset  to  the  current  character  within  the  text  identified  by  the 
cached  Superitem. 

cachedindex      Byte  offset  to  the  start  of  the  current  superitem  within  the  array  of 
Super i tems  stored  in  the  SuperBiock  referred  to  by 
cachedHandle. 

itemsPerBlock  Indicates  the  number  of  Superltems  Stored  in  each  SuperBiock. 
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SuperXtem 

Defines  an  individual  item  within  a  SuperBiock. 

■    Figure  49-11     supentem  layout 


length 


data 


Specifies  the  number  of  text  characters  in  the  TextEdit  record  that  are 
affected  by  this  Super  item.  A  value  of  $FFFFFFFF  indicates  that  this 
item  is  not  currently  used. 

Contains  the  actual  data  for  the  item. 
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Tabltem 


Contains  information  defining  an  absolute  tab  position,  expressed  as  a  pixel  offset  from 
the  left  margin  of  the  text  rectangle  (viewRect  of  the  TERecord).  The  TERuier 
structure  contains  an  array  of  Tabitems  whenever  the  user  has  defined  absolute  tabs. 


Figure  49-12     Tabltem  layout 
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tabKind  Must  be  set  to  $0000. 

tabData  Location  of  the  absolute  tab,  expressed  as  the  number  of  pixels  to 

indent  from  the  left  edge  of  the  text  rectangle  (viewRect  of 

TERecord). 
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TextBlock 

Contains  the  actual  text  for  the  record.  The  TextBlock  substructure  defines  a  linked-list 
which  stores  the  text.  A  TextList  substructure  within  the  TERecord  contains  access 
information  into  the  chain  of  TextBiocks  for  the  TextEdit  record.  The  TextBlock 
chain  stores  the  text  for  the  TextEdit  record  in  sequential  order.  That  is,  the  first 
TextBlock  contains  the  first  block  of  text,  the  second  TextBlock  contains  the  next 
block  of  text,  and  so  on. 


■    Figure  49-13    TextBlock  layout 
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nextHandle        Handle  to  the  next  TextBlock  in  the  chain  of  blocks  for  this  text 
record.  A  value  of  NIL  indicates  the  end  of  the  chain. 

prevHandle        Handle  to  the  previous  TextBlock  in  the  chain  of  blocks  for  this 
text  record.  A  value  of  NIL  indicates  the  beginning  of  the  chain. 

textLength        The  number  of  text  bytes  stored  at  theText. 

flags  Reserved. 

Reserved  Reserved 

theText  Text  for  the  record.  The  textLength  field  specifies  the  length  of 

this  array. 
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TeztList 

Identifies  the  current  position  within  the  text  for  the  record,  which  is  stored  in 
TextBiocks.  The  TERe cord  contains  a  TextList  substructure. 


■    Figure  49-14    TextList  layout 
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cachedHandle    Handle  to  the  TextBiock  containing  the  text  corresponding  to  the 
current  location. 

cachedOf  f  set      Byte  offset  within  the  TextBiock  referred  to  by  cachedHandle 
corresponding  to  the  current  location. 
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TextEdit  housekeeping  routines 

The  following  sections  describe  the  standard  housekeeping  calls  in  the  TextEdit  Tool  Set. 

TEBootlnit     $0122 

Initializes  TextEdit;  called  only  by  the  Tool  Locator. 
Parameters  None 

Errors  None 
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TEStartUp     $0222 

Starts  up  the  TextEdit  tool  set,  and  prepares  TextEdit  for  use  by  an  application  by 
allocating  memory  and  formatting  direct-page  space.  Application  programs  must  issue 
this  call  before  any  other  TextEdit  tool  calls,  Before  exiting,  applications  that  issue  the 
TEStartUp  call  must  call  TEShutDown  to  de-initialized  TextEdit. 

Parameters 

Stack  before  call 


Previous  contents 


userlD 


directPage 


Stack  after  call 


Word— Application's  User  ID  (obtained  at  program  start  time) 
Word— Address  of  one  page  of  direct-page  memory 
<— SP 


Previous  contents 


Errors 


<— SP 

$2201        teAireadyStarted        TextEdit  has  already  been  started 
Memory  Manager  errors  Returned  unchanged 

extern  pascal   void  TEStartUp (userlD,    directPage); 
Word  userlD,    directPage; 
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TEShutDown     $0322 

Frees  memory  used  by  TextEdit  on  behalf  of  an  application,  not  including  individual 
TextEdit  records— it  is  the  application's  responsibility  to  issue  the  tekhi  tool  call  at 
the  end  of  each  TextEdit  record.  Every  application  that  uses  TextEdit  must  issue  this  call 
before  exiting.  During  application  initialization,  applications  that  use  TextEdit  must 
issue  the  TEStartup  tool  call  before  any  other  TextEdit  calls. 

Parameters 

Stack  before  call 


Previous  contents 


<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


<— SP 

$2202        teNotstarted  TextEdit  has  not  been  started 

extern  pascal  void  TEShutDown () ; 
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TEVersion    $0422 

Retrieves  the  Resource  Manager  version  number.  This  call  returns  valid  information  if 
TextEdit  has  been  loaded;  the  tool  set  need  not  be  active.  The  versionlnfo  result  will 
contain  the  information  in  the  standard  format  defined  in  Appendix  A,  "Writing  Your  Own 
Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


versionlnfo 


Errors 


None 


Word— TextEdit  version  number 
<— SP 


extern  pascal  Word  TEVersion (); 


TEReset    $0522 

Resets  TextEdit;  called  only  when  the  system  is  reset. 
Parameters  None 

Errors  None 
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TEStatus     $0622 

Returns  a  flag  indicating  whether  TextEdit  is  active.  If  TextEdit  has  not  been  loaded,  your 
program  receives  a  Tool  Locator  error  (tooiNotFoundErr). 

♦   Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  TEStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  TextEdit  is  not  active,  the  returned  value  will  be  FALSE 
(NIL). 


Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


activeFlag 


Errors 
C 


Word— Boolean;  TRUE  if  TextEdit  is  active 
<— SP 

None 

extern  pascal  Word  TEStatus (); 
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TextEdit  tool  calls 


The  following  sections  describe  the  TextEdit  tool  calls,  in  order  by  call  name. 


TEActivate    $0F22 

Makes  the  specified  TextEdit  record  active— that  is,  makes  that  record  the  target  of  user 
keystrokes.  TextEdit  highlights  the  current  selection  or  displays  the  caret,  as  appropriate. 
User  editing  activity  now  applies  to  this  TextEdit  record. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls  with  TaskMaster,  it  should  not  issue  this  call;  TaskMaster 
manages  the  control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Stack  after  call 


Long— Handle  of  TERecord  in  memory 
<— SP 


Previous  contents 


Errors 


$2202 
$2203 


<— SP 

teNotStarted 
telnvalidHandle 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 

TERecord 


extern  pascal  void  TEActivate (teHandle) ; 
Long      teHandle; 
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TEClear    $1922 

Clears  the  current  selection  in  the  active  TextEdit  record  and  redraws  the  screen.  If  there  is 
no  current  selection,  then  this  call  does  nothing  and  returns  immediately.  This  call  does  not 
affect  the  desk  scrap. 

Note  that  this  call  does  not  generate  any  update  events;  it  directly  redraws  the  active 
record. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls  and  TaskMaster,  it  should  not  issue  this  call;  TaskMaster 
manages  the  control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Stack  after  call 


Long — Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


Errors 
C 

teHandle 


<— SP 

$2202        teNotstarted  TextEdit  has  not  been  started 

extern  pascal   void  TEClear (teHandle) ; 


Long 


teHandle; 


Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEClick     $1122 

Tracks  the  mouse  within  a  TextEdit  record,  selecting  all  text  that  it  passes  over  until  the 
user  releases  the  mouse  button.  If  the  user  holds  down  the  Shift  key,  this  call  extends  the 
current  selection  to  include  the  new  text.  TextEdit  automatically  scrolls  the  text  in  the 
proper  direction  if  the  user  drags  the  mouse  outside  the  view  rectangle. 

This  call  handles  double-  and  triple-clicks  as  follows:  double-clicks  select  a  word,  dragging 
lengthens  or  shortens  the  selection  in  word  increments;  triple-clicks  select  a  line,  dragging 
lengthens  or  shortens  the  selection  in  line  increments. 

If  your  program  issues  this  call  for  a  TextEdit  record  that  is  not  currentiy  active,  TextEdit 
first  makes  that  record  active,  then  proceeds  to  track  the  mouse. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records,  If  your 
program  uses  TextEdit  controls  with  TaskMaster,  it  should  not  issue  this  call;  TaskMaster 
manages  the  control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


-  eventRecordPtr  - 


teHandle 


Long— Pointer  to  event  record  for  the  mouse  click 

Long— Handle  of  TERecord  in  memory 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$2203 


<— SP 

teNotStarted 
telnvalidHandle 


Memory  Manager  errors 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 

TERecord 

Returned  unchanged 


49-76     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


extern  pascal  void  TEClick (eventRecordPtr, 
teHandle) ; 


Pointer 
Long 


eventRecordPtr; 
teHandle; 


eventRecordPtr 


Points  to  the  event  record  describing  the  mouse  click.  The  what, 
when,  where,  and  modifiers  fields  of  the  event  record  must  be  set. 
TextEdit  ignores  the  message  field.  For  information  on  the  format 
and  content  of  event  records,  see  Chapter  7,  "Event  Manager,"  in  the 
Toolbox  Reference. 
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TECompactRecord 


$1728 


Compacts  all  the  TextEdit  data  structures  in  a  specified  TextEdit  record. 
TECompactRecord  reclaims  space  used  for  deleted  lines  and  style  items,  and  for  styles 
that  are  no  longer  referenced  from  the  text.  While  this  call  may  be  issued  by  any 
application  that  uses  TextEdit,  it  is  intended  to  be  used  from  within  an  out-of-memory 
routine  (see  Chapter  36,  "Memory  Manager  Update,"  in  this  book  for  information  about 
out-of-memory  routines  and  the  out-of-memory  queue). 

Note  that  your  program  may  not  pass  a  NULL  TextEdit  record  handle  to  this  tool  call. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Stack  after  call 


Long— Handle  of  TERecord  to  compact 
<— SP 


Previous  contents 


Errors 


<— SP 

$2202         teNotStarted 
Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


teHandle 


extern  pascal  void  TECompactRecord (teHandle) ; 

Long      teHandle; 

Specifies  the  TextEdit  record  for  the  operation. 
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TECopy    $1722 

Copies  the  current  selection  from  the  active  TextEdit  record  to  the  desk  scrap, 
destroying  the  previous  desk  scrap  contents.  This  call  copies  both  the  text  and  style 
information  to  the  scrap.  Note,  however,  that  if  there  is  no  current  selection,  then  this  call 
does  nothing,  and  does  not  affect  the  desk  scrap. 

This  call  does  not  automatically  scroll  to  the  current  selection. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$2202         teNotStarted 
Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


extern  pascal  void  TECopy (teHandle) ; 


teHandle 


Long 


teHandle; 


Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TECut     $1622 


Copies  the  current  selection  from  the  active  TextEdit  record  to  the  desk  scrap, 
destroying  the  previous  desk  scrap  contents.  TECut  then  scrolls  to  the  beginning  of  the 
selection,  deletes  it,  and  then  redraws  the  screen.  This  call  copies  both  the  text  and  style 
information  to  the  scrap.  Note,  however,  that  if  there  is  no  current  selection,  then  this  call 
does  nothing,  and  does  not  affect  the  desk  scrap. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 
$2202  teNotStarted 

Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


extern  pascal  void  TECut (teHandle) ; 


teHandle 


Long 


teHandle; 


Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEDeactivate     $1022 

Deactivates  a  TextEdit  record.  Your  program  specifies  the  TERecord  for  the  record  in 
question.  TEDeactivate  changes  the  highlighting  for  the  current  selection  in  that  record 
to  show  that  it  is  inactive.  Any  user  editing  actions  (keystrokes,  cut  and  paste)  have  no 
effect  on  the  deactivated  record. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$2203 


<— SP 

teNotStarted 
telnvalidHandle 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 


extern  pascal  void  TEDeactivate (teHandle)  ; 


Long 


teHandle; 
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TEGetDefProc     $2222 


Returns  the  address  of  the  TextEdit  control  definition  procedure.  The  system  issues  this 
call  when  the  Control  Manager  starts  up  in  order  to  obtain  the  address  of  the  TextEdit 
control  definition  procedure.  This  call  is  not  intended  for  application  use. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


de/ProcPtr     - 


Errors 
C 


None 


Long— Pointer  to  control  definition  procedure 
<— SP 


extern  pascal  Pointer  TEGetDefProc ()  ; 
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TEGetlnternalProc     $2622 

Returns  a  pointer  to  the  low-level  procedure  routine  for  TextEdit. 

This  call  is  reserved  for  future  use  by  application  programs  to  access  certain  low-level 
TextEdit  routines. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


-  internalProcPtr  -  Long— Pointer  to  internal  low-level  procedure  routine 

<— SP 

Errors  None 

C  extern  pascal  Pointer  TEGetlnternalProc {)  ; 
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TEGetLastError     $2722 

Returns  the  last  error  code  generated  for  a  TextEdit  record.  Your  program  specifies  the 
TERecord  for  the  appropriate  record  and  a  flag  indicating  whether  to  clear  the  last  error 
code  after  the  call.  TextEdit  then  returns  the  last  error  code  for  that  record,  and,  if 
requested,  clears  the  last  error  field. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


clearFlag 


teHandle 


Stack  after  call 


Word— Space  for  result 

Word— Flag  controlling  disposition  of  last  error  field  for  record 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 

<— SP 


Previous  contents 


lastError 


Errors 
C 


$2202 


Word— Last  error  code  generated  for  the  record 
<— SP 


teNotStarted 


TextEdit  has  not  been  started 


extern  pascal  Word  TEGetLastError (clearFlag, 
teHandle) ; 


clearFlag 


$0000 
$FFFF 


Word 
Long 


clearFlag; 

teHandle; 


Controls  what  TextEdit  does  with  the  last  error  field  after  servicing  the 
call: 

Leaves  the  last  error  code  intact 
Clears  the  last  error  code  to  $0000 
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TEGetRuler     $2322 

Returns  the  ruler  definition  for  a  TextEdit  record.  Your  program  specifies  the  destination 
for  the  ruler  information  and  the  TERecord  corresponding  to  the  appropriate  record. 
TEGetRuler  returns  the  TERuier  record  defining  the  ruler  for  the  record  in  question. 

Parameters 

Stack  before  call 


Previous  contents 


rulerDescriptor 


ruierRef 


teHandle 


Stack  after  call 


Word— Defines  type  of  reference  in  ruierRef 

Long— Reference  to  buffer  to  receive  TERuier  record 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


Errors 
C 


$2202 


<— SP 

teNotStarted 


TextEdit  has  not  been  started 


extern  pascal  void  TEGetRuler (rulerDescriptor, 
ruierRef,  teHandle) ; 

Word      rulerDescriptor; 
Long      ruierRef,  teHandle; 
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rulerDescriptor 

reflsPointer 
ref IsHandle 
reflsResource 
ref IsNewHandle 


Defines  the  type  of  reference  stored  in  rulerRef. 


teHandle 


$0000         rulerRef  contains  a  pointer  to  a  buffer  to  receive  the 
TERuier  structure 

$0001  rulerRef  'contains  a  handle  to  a  buffer  to  receive  the 

TERuier  structure 

$0002         rulerRef  contains  a  resource  ID  which  can  be  used  to 
access  a  buffer  to  receive  the  TERuier  structure 

$0003  rulerRef  contains  a  pointer  to  a  four-byte  buffer  to 

receive  a  handle  to  the  TERuier  structure; 
TEGetRuier  allocates  the  new  handle  and  returns  it 
in  the  specified  buffer 

Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEGetSelection     $1C22 

Returns  information  defining  the  current  selection  for  a  TextEdit  record.  Your  program 
specifies  the  TERecord  for  the  record  in  question.  TEGetSelection  then  determines 
the  starting  and  ending  byte  offsets  for  the  current  selection,  and  returns  those  values  into 
locations  specified  by  your  program. 

Both  offset  values  are  stored  as  four-byte  long  values.  If  there  is  no  current  selection  for 
the  specified  record,  both  the  starting  and  ending  offsets  will  contain  the  current  caret 
position. 

Parameters 

Stack  before  call 


Previous  contents 


-    selectionStart   - 


-    selectionEnd    - 


teHandle 


Stack  after  call 


Long— Pointer  to  buffer  to  receive  starting  offset  value 

Long— Pointer  to  buffer  to  receive  ending  offset  value 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


Errors 
C 


$2202 


<— SP 
teNotStarted 


TextEdit  has  not  been  started 


extern  pascal  void  TEGetSelection (selectionStart, 
selectionEnd,  teHandle) ; 


teHandle 


Pointer   selectionStart,  selectionEnd; 
Long      teHandle; 

Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEGetSelectionStyle     $1E22 

Returns  all  style  information  for  the  text  in  the  current  selection  in  a  TextEdit  record.  Your 
program  specifies  the  TERecord  for  the  record  in  question  and  the  addresses  of  buffers 
to  receive  the  style  data.  TEGetSelectionStyle  then  loads  the  main  output  buffer 
with  TEStyle  structures  describing  all  styles  affecting  text  in  the  current  selection.  The 
first  word  in  the  buffer  contains  a  counter  indicating  the  number  ofTEStyle  structures 
returned. 

TEGetSelectionStyle  also  builds  a  common  style  record,  which  contains  all  style 
elements  which  are  common  to  all  text  in  the  selection.  A  flag  word  directs  your  program 
to  the  relevant  portions  of  the  common  style  record,  which  is  also  inTEStyle  format. 

If  there  is  no  current  selection,  TEGetSelectionStyle  returns  the  null  style  record, 
which  defines  the  style  that  will  be  applied  to  any  text  inserted  at  the  current  caret 
position. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


-  commonStylePt  - 


-     styleHandle 


teHandle 


Stack  after  call 


Word— Space  for  result 

Long— Pointer  to  TEStyle  buffer  for  common  style  record 

Long— Handle  to  buffer  for  style  information 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 

<— SP 


Previous  contents 


commonFlag 


Errors 


Word— Bit  flag  describing  common  style  record  contents 
<— SP 


$2202         teNotStarted 


TextEdit  has  not  been  started 


49-88     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  11GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


C  extern  pascal  Word 

TEGetSelectionStyle (commonStylePtr, 
styleHandle,  teHandle) ; 

Pointer    commonStylePtr; 

Long      styleHandle,  teHandle; 

commonStylePtr    Points  to  a  buffer  to  receive  a  formatted  TEStyle  structure 

containing  the  style  elements  that  are  common  to  all  text  in  the  current 
selection.  commonFlag  indicates  which  portions  of  this  TEStyle 
structure  contain  valid  data. 

styleHandle  Handle  to  a  buffer  to  receive  the  style  information  for  the  current 

selection.  TEGetSelectionStyle  returns  as  many  TEStyle 
structures  as  are  required  to  fully  specify  all  the  styles  in  the  selection. 
If  the  buffer  referenced  by  styleHandle  cannot  store  enough  TEStyle 
structures,  TEGetSelectionStyle  automatically  resizes  the  handle 
memory. 

On  return  from  TEGetSelectionStyle,  the  buffer  referenced  by 
styleHandle  will  be  formatted  as  follows: 


$00 
$02 


style 


-   Word 
'■  Array  of  TEStyle  structures 


count  Indicates  the  number  of  TEStyle  structures  in  the  styles 

array. 

styles  Array  of  count  TEStyle  structures. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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commonFlag 

Reserved 

fUseFont 


fUseSize 


fUseForeColor 


fUseBackColor 


fUseUserData 


fUseAttributes 


Indicates  which  portions  of  the  common  style  record  pointed  to  by 
commonStylePtr  are  relevant: 


bits  6-15 
bit  5 


bit  4 


bit  3 


bit  2 


bitl 


bitO 


Will  be  set  to  0 

The  font  family  defined  by  the  font  id  field  of  the 

common  style  record  is  valid; 

1  -  Font  family  valid 

0  -  Font  family  not  valid 

The  font  size  defined  by  the  font  id  field  of  the 
common  style  record  is  valid: 

1  -  Font  size  valid 

0  -  Font  size  not  valid 

The  fore  color  field  of  the  common  style  record  is 
valid: 

1  -  f  oreColor  valid 

0  -  f  oreColor  not  valid 

The  backcoior  field  of  the  common  style  record  is 

valid: 

1-backColor  valid 

0  -  backColor  not  valid 

The  userData  field  of  the  common  style  record  is 
valid: 

1  -  userData  valid 

0- userData  not  valid 

The  attributes  defined  by  the  font  id  field  of  the 

common  style  record  is  valid: 

1  -  Font  attributes  valid 

0  -  Font  attributes  not  valid 


49-90    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  11GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


TEGetText     $0C22 

Returns  the  text  from  a  TextEdit  record,  including  the  style  information  associated  with 
that  text.  Your  program  specifies  the  TERecord  for  the  record  in  question,  the  format 
for  the  returned  text,  and  buffers  to  receive  the  text  and  style  data.  TEGetText  places 
the  text  in  the  return  buffer  in  the  format  requested  by  your  program;  style  information  is 
returned  in  a  TEFormat  structure. 

In  addition,  TEGetText  returns  a  value  indicating  the  total  length  of  the  text  in  the 
TextEdit  record.  This  value  represents  the  number  of  bytes  of  text  in  the  record,  not  the 
number  of  bytes  loaded  into  the  return  buffer.  If  the  return  buffer  is  too  small  to  receive 
all  the  record  text,  TEGetText  returns  a  teBuf  f  erOverf  low  error.  This  error  is  also 
returned  if  the  text  is  too  large  to  be  returned  in  the  specified  format  (for  example,  the 
record  contains  300  text  characters  and  your  program  requested  an  output  Pascal  string). 

Parameters 

Stack  before  call 


Previous  contents 


Space 


bufferDescriptor 


bufferRef      - 


bufferLength    - 


styleDescriptor 


styleRef 


teHandle 


Long— Space  for  result 

Word— Defines  the  format  for  text  returned  at  bufferRef 

Long— Reference  to  the  output  text  buffer 

Long— Length  of  the  buffer  referred  to  by  bufferRef 

Word— Defines  the  type  of  reference  stored  in  styleRef 

Long— Reference  to  buffer  for  TEFormat  structure  defining  style 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


textLength 


Long— Total  length  of  all  text  in  record 
<— SP 
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Errors  $2202        teNotstarted  TextEdit  has  not  been  started 

$2203        teinvaiidHandie  teHandle  does  not  refer  to  a  valid 

TERecord 
$2204        teinvaiidoescriptor  Invalid  descriptor  value  specified 
$2208        teBuf  f  eroverf  low        The  output  buffer  was  too  small 

to  accept  all  data 
Memory  Manager  errors  Returned  unchanged 

C  extern  pascal  Long  TEGetText (buf f erDescriptor, 

bufferRef,  buf ferLength,  styleDescriptor,  styleRef, 
teHandle) ; 

Long      bufferRef,  buf ferLength,  styleRef, 

teHandle; 
Word      bufferDescriptor,  styleDescriptor; 

bufferDescriptor     Defines  the  format  in  which  TEGetText  should  return  the  record  text, 
and  the  type  of  reference  stored  in  bufferRef. 

Reserved  bits  5-16     Must  be  set  to  0 

ref  Format  bits  3-4      Defines  the  type  of  reference  stored  in  bufferRef 

00  -  bufferRef  is  a  pointer  to  the  output  buffer; 
bufferLength  contains  the  length  of  the  buffer  (in 
bytes) 

01  -  bufferRef  'is  a  handle  to  the  output  buffer; 
bufferLength  is  ignored 

10  -  bufferRef  "is  a  resource  ID  for  the  output  buffer 
(TextEdit  will  create  the  resource  if  it  does  not 
already  exist);  bufferLength  is  ignored 

11  -  bufferRef  'is  a  pointer  to  a  four-byte  buffer  to 
receive  a  handle  to  the  output  text;  TEGetText 
allocates  the  handle;  bufferLength  is  ignored 
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dataFormat 


bufferLength 


styleDescriptor 


reflsPointer 


ref IsHandle 


ref IsResource 


reflsNewHandle 


styleRef 


bits  0-2       Defines  the  format  for  the  output  text: 

000  -  Output  data  will  be  formatted  as  a  Pascal  string 
(resource  type  of  rPString) 

001  -  Output  data  will  be  formatted  as  a  C  string 
(resource  type  of  rcstring) 

010  -  Output  data  will  be  formatted  as  a  Class  1 
GS/OS  input  string  (resource  type  of 

rCl Input St ring) 

011  -  Output  data  will  be  formatted  as  a  Class  1 
GS/OS  output  string  (resource  type  of 
rcioutputstring);  application  need  not  set  the 
buffer  size  field 

100  -  Output  data  will  be  formatted  for  input  to 
LineEdit  TextBox2  tool  call  (resource  type  of 
rTextBox2)— see  Chapter  10,  "LineEdit  Tool  Set," 
in  the  Toolbox  Reference  for  details 

101  -  Output  data  will  be  returned  as  an  unformatted 
text  block  (resource  type  of  rText) 

110  -  Invalid 

111  -  Invalid 

Defines  the  length  of  the  output  buffer  referenced  by  bufferRef,  if 
ref  Format  indicates  that  bufferRef contains  a  pointer.  For  other 
types  of  references,  this  field  is  ignored. 

Defines  the  type  of  reference  stored  in  styleRef. 

$0000         s/yfe/te/contains  a  pointer  to  a  buffer  to  receive  the 

te Format  structure 
$0001         styleRef  contains  a  handle  to  a  buffer  to  receive  the 

TEFormat  structure 
$0002         styleRef  contains  a  resource  ID  which  can  be  used  to 

access  a  buffer  to  receive  the  TEFormat  structure 
$0003         styleRef  contains  a  pointer  to  a  four-byte  buffer  to 

receive  a  handle  to  the  TEFormat  structure; 

TEGetText  allocates  the  new  handle  and  returns  it  in 

the  specified  buffer 

Reference  to  buffer  to  receive  style  information,  in  TEFormat 
structure  form.  If  this  field  is  set  to  NULL,  then  TEGetText  will  not 
return  any  style  information,  and  will  ignore  styleDescriptor. 
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teHandle 


textLength 


Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 

Indicates  the  number  of  bytes  of  text  in  the  record.  Note  that  this 
value  may  exceed  the  number  of  bytes  returned  at  bufferRef,  if  the 
referenced  buffer  is  too  small  to  receive  all  the  text.  In  this  case, 
TEGetText  also  returns  a  teBuf  feroverf  low  error  code. 
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TEGetTextlnfo     $0D22 


Returns  a  variable-sized  information  record  describing  a  TextEdit  record.  Your  program 
specifies  the  TERecord  for  the  TextEdit  record  in  question,  the  address  of  a  buffer  to 
receive  the  information  record,  and  a  value  indicating  how  much  data  TEGetTextlnfo 
should  return.  The  system  returns  the  appropriate  data  at  the  specified  location. 


Parameters 

Stack  before  call 


Previous  contents 


-     infoRecPtr     - 


parameterCount 


teHandle 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$2203 

$2206 


Long— Pointer  to  buffer  for  information  record 

Word— Specifies  the  number  of  fields  to  return 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 

<— SP 


<— SP 

teNotStarted 
telnvalidHandle 

telnvalidPCount 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 

TERecord 

Invalid  parameter  count  value 

specified 


extern  pascal  void  TEGetTextlnfo (infoRecPtr, 
parameterCount,  teHandle) ; 


Pointer 

infoRecPtr; 

Long 

teHandle; 

Word 

parameterCount ; 
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infoRecPtr  Points  to  a  buffer  to  receive  a  partial  or  complete  information  record, 

depending  upon  the  value  of  parameterCount.  The  information  record 
is  formatted  as  follows  (future  versions  of  TextEdit  may  add  fields  to 
the  end  of  this  record): 


$00 


$04 


$08 


$0C 


$10 


$14 


charCount     —  Long 


HneCount     -  Long 


formatMemory    —  1-Ong 


—    totalMemory    -  Long 


styleCount     —  Long 


—    rulerCount     —  Long 


charCount  Contains  the  number  of  text  characters  in  the  record. 

linecount  Contains  the  number  of  lines  in  the  record.  A  line  is  defined  as  all 

text  that  is  displayed  on  a  single  line  of  the  screen,  based  upon 
the  current  display  options. 

formatMemory    The  amount  of  memory  (in  bytes)  required  to  store  the  style 
information  for  the  record. 

totalMemory      The  amount  of  memory  (in  bytes)  required  for  the  record, 
including  both  text  and  style  data. 

styleCount        The  number  of  unique  styles  defined  for  the  record. 

rulerCount        The  number  of  rulers  defined  for  the  record. 
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parameterCount     Specifies  the  number  of  information  record  fields  to  be  returned  by 
TEGetTextinf  o.  Valid  values  lie  in  the  range  from  1  to  6.  Values 
outside  this  range  yield  a  teinvaiidPCount  error  code.  The 
returned  data  always  begin  with  the  charCount  field,  and  continue 
until  the  specified  number  of  fields  have  been  formatted. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEIdle    $0E22 

Provides  processor  time  to  TextEdit  so  that  it  can  blink  the  cursor  and  perform 
background  tasks.  Your  program  specifies  the  TERecord  for  the  record.  TextEdit  then 
determines  whether  enough  time  has  elapsed  to  require  a  cursor  blink,  and,  if  so,  blinks 
the  cursor.  In  addition,  TextEdit  performs  any  necessary  background  processing  for  the 
record. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Your  program  should  call  TEidie  often— usually  every  time  through  the  main  event  loop, 
and  periodically  during  time-consuming  operations.  If  your  program  does  not  call  TEidie 
often  enough,  the  cursor  will  blink  irregularly.  TextEdit  ensures  that  the  cursor  blink  rate 
does  not  exceed  that  specified  by  the  user's  control  panel  setting. 


Parameters 

Stack  before  call 

Previous  contents 

teHandle 

Long— Handle  of  TERecord  in  memory 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                   $2202 

teNotstarted               TextEdit  has  n< 

C 

exte 

m  pascal   void  TEIdle (teHandle) ; 
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TEInsert     $1A22 


Inserts  a  block  of  text  before  the  current  selection  in  a  TextEdit  record,  and  then  redraws 
the  text  screen.  Your  program  specifies  the  text  and  style  data  to  be  inserted  and  the 
TERecord  for  the  record.  TEInsert  then  inserts  the  text  and  style  data  at  the  current 
selection. 

This  call  does  not  affect  the  desk  scrap. 

Parameters 

Stack  before  call 


Previous  contents 


textDescriptor 


textRef 


textLength 


styleDescriptor 


styleRef 


teHandle 


Word— Defines  the  format  for  text  stored  at  textRef 
Long— Reference  to  the  input  text  buffer 
Long— Length  of  the  buffer  referred  to  by  textRef 
Word— Defines  the  type  of  reference  stored  in  styleRef 
Long— Reference  to  TEFormat  structure  defining  style  for  text 
Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$220C 


<— SP 

teNotStarted 
teInvalidTextBox2 


Memory  Manager  errors 


TextEdit  has  not  been  started 
The  TextBox2  format  codes 
were  inconsistent 
Returned  unchanged 


extern  pascal  void  TEInsert (textDescriptor,  textRef, 
textLength,  styleDescriptor,  styleRef, 
teHandle) ; 

Long      textRef,  textLength,  styleRef,  teHandle; 
Word      textDescriptor,  styleDescriptor; 
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textDescriptor        Defines  the  format  of  the  text  to  be  inserted,  and  the  type  of 
reference  stored  in  texlRef. 

Reserved  bits  5-16     Must  be  set  to  0 

ref  Format  bits  3-4       Defines  the  type  of  reference  stored  in  textRef. 

00  -  textRef  \s  a  pointer  to  the  text  buffer;  textLength 
contains  the  length  of  the  buffer  (in  bytes) 

01  -  textRef  "is  a  handle  to  the  text  buffer;  textLength  is 
ignored 

10  -  textRef  "is  a  resource  ID  for  the  text  buffer; 
textLength  is  ignored 

11  -Invalid 
dataFormat              bits  0-2      Defines  the  format  of  the  text: 

000  -  Text  is  a  Pascal  string  (resource  type  of 
rPString) 

001  -  Text  is  a  C  string  (resource  type  of  rest  ring) 

010  -  Text  is  a  Class  1  GS/OS  input  string  (resource 
type  of  rCl  Input  St  ring) 

011  -  Text  is  a  Class  1  GS/OS  output  string  (resource 

type  Of  rClOutputString) 

100  -  Text  is  formatted  for  input  to  LineEdit 
TextBox2  tool  call  (resource  type  of 
rTextBox2>— see  Chapter  10,  "LineEdit  Tool  Set," 
in  the  Toolbox  Reference  for  details;  style  data  in  the 
text  overrides  that  specified  by  styleRef 

101  -  Text  is  an  unformatted  text  block  (resource 
type  of  rText) 

110  -  Invalid 
111 -Invalid 

textLength  Defines  the  length  of  the  buffer  referenced  by  textRef  This  field  is  only 

valid  for  reference  types  that  do  not  contain  length  data  (see 
textDescriptor).  For  other  types  of  references,  this  field  is  ignored. 

styleDescriptor       Defines  the  type  of  reference  stored  in  styleRef. 


reflsPointer  $0000 

reflsHandle  $0001 

reflsResource  $0002 


styleRef  contains  a  pointer  to  a  TEFormat  structure 
styleRef  contains  a  handle  to  a  TEFormat  structure 
styleRef  contains  a  resource  ID  which  can  be  used  to 
access  a  buffer  containing  the  TEFormat  structure 
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styleRef 


teHandle 


Reference  to  buffer  containing  style  information,  in  TEFormat 
structure  form.  If  this  field  is  set  to  NULL,  then  TEinsert  will  use  the 
style  of  the  first  character  in  the  current  selection  for  the  record,  and 
will  ignore  styleDescriptor. 

Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEKey    $1422 

Processes  a  keystroke  for  a  TextEdit  record.  Your  program  specifies  the  TERecord  for 
the  record  and  the  event  record  for  the  keystroke.  TEKey  then  processes  the  key.  If  the 
keystroke  is  a  control  key  (one  that  requires  special  processing,  as  outlined  in  "Standard 
TextEdit  key  sequences"  earlier  in  this  chapter),  TEKey  performs  the  appropriate 
TextEdit  action.  If  the  keystroke  is  not  a  control  key,  TEKey  inserts  the  corresponding 
character  into  the  text  of  the  target  TextEdit  record  at  the  current  selection. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Your  program  should  issue  this  call  in  response  to  KeyDown  or  AutoKey  events. 

Parameters 

Stack  before  call 


Previous  contents 


-  eventRecordPtr 


teHandle 


Long— Pointer  to  event  record  for  the  key 
Long— Handle  of  TERecord  in  memory 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$2202         teNotStarted 
Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


C  extern  pascal  void  TEKey (eventRecordPtr,  teHandle) 

Pointer   eventRecordPtr; 
Long      teHandle; 

eventRecordPtr      Points  to  the  event  record  describing  the  keystroke.  For  information 
on  the  format  and  content  of  event  records,  see 
Chapter  7,  "Event  Manager,"  in  the  Toolbox  Reference. 
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TEKill    $0A22 

Deallocates  a  TERecord  and  all  associated  memory.  Your  program  specifies  the 
TERecord  to  be  freed.  tekIii  then  releases  the  record  and  any  memory  supporting  it. 
TEKill  does  not  erase  or  invalidate  the  screen,  nor  does  it  make  another  record  the 
target  if  the  target  record  is  killed.  Your  program  must  take  care  of  these  duties. 

Your  program  should  issue  this  call  only  when  it  is  completely  through  with  the  TERecord 
and  its  TextEdit  record— all  text  associated  with  the  record  is  lost  after  this  call. 

If  your  program  uses  TextEdit  controls  it  may  issue  the  Kilicontrois  or 
DisposeControi  Control  Manager  tool  calls  instead  of  tekiii. 


Parameters 

Stack  before  call 

Previous  contents 

teHandle 

Long— Handle  of  t 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Em 

ars                   $2202 
$2203 

teNotStarted 
telnvalidHandle 

TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 


extern  pascal  void  TEKill (teHandle) ; 
Long      teHandle; 
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TENew     $0922 

Allocates  a  new  TextEdit  record  in  the  current  port,  and  returns  the  TERecord  defining 
that  record.  Your  program  specifies  the  parameters  for  that  record  in  a  TEParamBiock 
structure  (see  "TextEdit  data  structures"  earlier  in  this  chapter  for  information  on  the 
format  and  content  of  the  TEParamBiock).  TextEdit  then  allocates  and  formats  the 
TERecord  for  the  record. 

The  bounds  rectangle  specified  in  the  TEParamBiock  must  be  large  enough  to 
completely  enclose  a  single  character  in  the  largest  allowable  font  for  the  record. 

Your  program  should  issue  this  call  only  if  it  is  not  using  TextEdit  controls.  In  order  to 
create  a  TextEdit  control,  use  the  NewControi2  Control  Manager  tool  call  (see 
Chapter  28,  "Control  Manager  Update,"  in  this  book).  Note  that  NewControi2  may  be 
used  to  create  several  controls  at  once. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


-  parameterBlock  - 


Long— Space  for  result 

Long — Pointer  to  formatted  TEParamBiock 

<— SP 


Stack  after  call 


Previous  contents 


teHandle 


Errors 


Long— Handle  to  new  TERecord 
<— SP 


teNotstarted  TextEdit  has  not  been  started 

teinvaiidDescriptor  Invalid  descriptor  value  specified 
telnvalidFlag  textFlagS  field  of  TEParamBiock 

is  invalid 
teinvaiidPCount  Invalid  parameter  count  value 

specified 
Memory  Manager  errors  Returned  unchanged 


$2202 
$2204 
$2205 

$2206 
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extern  pascal  Long  TENew (parameterBlock) ; 
Pointer   parameterBlock; 
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TEOffsetToPoint     $2022 

Converts  a  text  byte  offset  into  a  pixel  position  expressed  in  the  local  coordinates  of  the 
GrafPort  containing  the  TextEdit  record.  Your  program  specifies  the  byte  offset  to  the 
character  in  question,  the  addresses  of  buffers  to  receive  the  pixel  position  information, 
and  the  TERecord  for  the  record.  TEOf  f  setToPoint  then  determines  the  pixel 
position  for  the  character. 

The  returned  pixel  position  is  expressed  as  two  signed  long  integers.  If  the  specified 
offset  is  beyond  the  end  of  the  text  for  the  record,  TEOf  f  setToPoint  returns  the 
position  of  the  last  character.  Note  that  if  the  specified  character  lies  above  the  display 
rectangle,  the  vertical  position  component  will  be  a  negative  value.  The  pixel  position  is 
not  expressed  as  a  QuickDraw  II  point,  because  the  TextEdit  drawing  space  is  larger  than 
the  QuickDraw  II  drawing  space. 

The  TEPointToOf  f  set  call  performs  the  inverse  operation,  converting  a  pixel  position 
into  a  text  offset. 

Parameters 

Stack  before  call 


Previous  contents 


textOffset 


vertPosPtr 


-     horzPosPtr     - 


teHandle 


Stack  after  call 


Long— Byte  offset  to  text 

Long— Pointer  to  four-byte  buffer  to  receive  vertical  position 

Long— Pointer  to  four-byte  buffer  to  receive  horizontal  position 

Long — Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


Errors 


<— SP 
$2202         teNotStarted 


TextEdit  has  not  been  started 
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C  extern  pascal  void  TEOf f setToPoint (textOf f set, 

vertPosPtr,  horzPosPtr,  teHandle) ; 

Long      textOffset,  teHandle; 
Pointer   vertPosPtr,  horzPosPtr; 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEPaintText     $1322 

Prints  the  text  from  a  TextEdit  record.  Your  program  specifies  the  destination  rectangle 
and  GrafPort,  print  control  information,  and  the  TextEdit  record  from  which 
TEPaintText  is  to  print.  TextEdit  then  draws  the  appropriate  record  text  into  the 
specified  rectangle  and  GrafPort.  TEPaintText  begins  printing  at  a  line  number  you 
specify,  and  continues  until  the  destination  rectangle  has  been  filled.  The  routine  then 
returns  the  next  line  number  to  be  printed  so  that  your  program  can  issue  the  next  call 
correctly. 

Your  program  issues  this  tool  call  within  a  Print  Manager  job,  which  you  start  by  calling 
PrOpenDoc.  The  Print  Manager  returns  the  GrafPort  pointer  when  you  initiate  the  job. 
Refer  to  Chapter  15,  "Print  Manager,"  of  the  Toolbox  Reference  for  complete  information 
on  starting,  managing,  and  ending  a  print  job. 

Note  that  this  call  is  not  limited  to  printing;  your  application  can  use  this  tool  call  to  paint 
into  any  GrafPort. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


graJPort 


-     startingLine    - 


rectPtr 


flags 


teHandle 


Stack  after  call 


Long — Space  for  result 

Long — Pointer  to  destination  GrafPort 

Long— Starting  line  number  for  print  operation 

Long— pointer  to  the  destination  rectangle  in  GrafPort 
Word — Control  flags  for  the  print  operation 
Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


nextLine 


Long— Next  line  number  to  print 
<— SP 
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Errors 


startingLine 


grafPort 


rectPtr 


Ms 


Reserved 
teHandle 


$2202    teNotStarted 
$2209    telnvalidLine 


TextEdit  has  not  been  started 
Starting  line  value  is  greater  than 
the  number  of  lines  in  the  text 
(end-of-file) 


extern  pascal  Long  TEPaintText (grafPort, 

startingLine,  rectPtr,  flags,  teHandle) ; 

Pointer   grafPort,  rectPtr; 
Long      startingLine,  teHandle; 
Word      flags; 

Specifies  the  first  line  to  be  printed.  A  line  is  defined  as  all  text  that  is 
displayed  on  a  single  line  of  the  screen,  based  upon  the  current  display 
options. 

Points  to  a  QuickDraw  II  GrafPort  definition  which  describes  the 
destination  for  the  print  operation.  For  more  information  on  the 
format,  content,  and  use  of  the  GrafPort  structure,  see 
Chapter  16,  "QuickDraw  II,"  in  the  Toolbox  Reference. 

Points  to  a  structure  defining  the  destination  rectangle  for  the  print 
operation.  This  rectangle  essentially  defines  the  output  page  size,  and 
must  lie  in  the  output  GrafPort  specified  by  grafPort.  Each  print 
operation  initiated  by  TEPaintText  ends  when  the  rectangle 
described  by  the  structure  pointed  to  by  rectPtr  fills.  Refer  to  the 
description  of  the  PrOpenPage  tool  call  in 
Chapter  15,  "Print  Manager,"  of  the  Toolbox  Reference  for  more 
information  on  this  frame  rectangle. 

Controls  the  print  operation: 


fPartialLines 
fDontDraw 


bit  15         Reserved;  must  be  set  to  0 
bit  14         Controls  printing: 

0  -  Print  data 

1  -  Calculate  the  number  of  lines  that  will  fit  in  rectPtr, 
but  do  not  print—  nextLine  still  contains  next  line  to 
print  just  as  if  text  had  been  printed  (supports  page 
skip) 

bits  0-13     Must  be  set  to  0 

Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEPaste    $1822 

Replaces  the  current  selection  with  the  contents  of  the  desk  scrap,  including  both  text 
and  style  information.  Your  program  specifies  the  TERecord  for  the  TextEdit  record  in 
which  the  operation  is  to  take  place.  TEPaste  then  pastes  the  data  from  the  desk  scrap 
into  the  record  text.  If  the  desk  scrap  is  empty,  the  current  selection  is  untouched. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Stack  after  call 


Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


Errors 


<— SP 

$2202         teNotStarted 
Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


extern  pascal  void  TEPaste (teHandle) ; 


teHandle 


Long 


teHandle; 


Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEPointToOffset     $2122 

Converts  a  pixel  position  expressed  in  the  local  coordinates  of  the  GrafPort  containing 
the  TextEdit  record  into  a  text  byte  offset  into  the  text  for  the  record.  Your  program 
specifies  the  pixel  position  in  terms  of  its  relative  horizontal  and  vertical  location  in  the 
GrafPort,  but  not  as  a  QuickDraw  II  point.  TEPointToof  f  set  then  generates  the 
appropriate  text  offset  within  the  record. 

The  vertical  and  horizontal  components  of  the  pixel  position  are  represented  as  signed 
Long  integers.  If  the  specified  position  lies  before  the  first  text  character  in  the  record, 
then  the  returned  offset  will  be  $00000000.  If  the  position  is  after  the  last  text  character, 
the  call  returns  the  offset  of  the  last  character  in  the  record.  If  your  program  specifies  a 
horizontal  position  beyond  the  last  character  in  a  line,  TEPointToof  f  set  returns  the 
offset  of  the  last  character  in  the  line. 

The  TEOf  f  setToPoint  call  performs  the  inverse  operation,  converting  a  text  offset 
into  a  pixel  position. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


vertPos 


horzPos 


teHandle 


Long— Space  for  result 

Long— Vertical  position  component 

Long— Horizontal  position  component 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


textOffset 


Errors 


Long— Byte  offset  to  text  corresponding  to  pixel  position 
<— SP 


$2202         teNotStarted 


TextEdit  has  not  been  started 
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C  extern  pascal  Long  TEPointToOff set (vertPos,  horzPos, 

teHandle) ; 

Long      vertPos,  horzPos,  teHandle; 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEReplace     $1B22 

Replaces  the  current  selection  in  a  TextEdit  record  with  a  specified  block  of  text,  and 
then  redraws  the  text  screen.  Your  program  specifies  the  text  and  style  data  to  be 
inserted  and  the  TERecord  for  the  record.  TEReplace  then  inserts  the  text  and  style  data 
in  place  of  the  current  selection. 

This  call  does  not  affect  the  desk  scrap. 

Parameters 

Stack  before  call 


Previous  contents 


textDescriptor 


textRef 


textLength 


styleDescriptor 


styleRef 


teHandle 


Word— Defines  the  format  for  text  stored  at  textRef 
Long— Reference  to  the  input  text  buffer 

Long— Length  of  the  buffer  referred  to  by  textRef 
Word— Defines  the  type  of  reference  stored  in  styleRef 
Long— Reference  to  TEFormat  structure  defining  style  for  text 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 


$2202        teNotstarted  TextEdit  has  not  been  started 

$220C       teinvaiidTextBox2      The  TextBox2  format  codes 

were  inconsistent 
Memory  Manager  errors 


Returned  unchanged 


extern  pascal  void  TEReplace (textDescriptor, 

textRef,    textLength,    styleDescriptor, 
styleRef,    teHandle) ; 

Long  textRef,    textLength,    styleRef,    teHandle; 

Word  textDescriptor,    styleDescriptor; 
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textDescriptor        Defines  the  format  of  the  text  to  be  inserted,  and  the  type  of 
reference  stored  in  textRef. 

Reserved  bits  5-16     Must  be  set  to  0 

ref  Format  bits  3-4      Defines  the  type  of  reference  stored  in  textRef. 

00  -  textRef  is  a  pointer  to  the  text  buffer;  textLength 
contains  the  length  of  the  buffer  (in  bytes) 

01  -  textRef  is  a  handle  to  the  text  buffer;  textLength  is 
ignored 

10  -  textRef  is  a  resource  ID  for  the  text  buffer; 
textLength  is  ignored 

11  -  Invalid 
dataFormat              bits  0-2      Defines  the  format  of  the  text: 

000  -  Text  is  a  Pascal  string  (resource  type  of 

rPString) 

001  -  Text  is  a  C  string  (resource  type  of  rest  ring) 

010  -  Text  is  a  Class  1  GS/OS  input  string  (resource 
type  of  rCl  Input  St  ring) 

011  -  Text  is  a  Class  1  GS/OS  output  string  (resource 

type  Of  rClOutputString) 

100  -  Text  is  formatted  for  input  to  LineEdit 
TextBox2  tool  call  (resource  type  of  rTextBox2)— 
see  Chapter  10,  "LineEdit  Tool  Set,"  in  the  Toolbox 
Reference  for  details;  style  data  in  the  text  overrides 
that  specified  by  styleRef 

101  -  Text  is  an  unformatted  text  block  (resource 
type  of  rText) 

110  -  Invalid 

111  -  Invalid 

textLength  Defines  the  length  of  the  buffer  referenced  by  textRef.  This  field  is  only 

valid  for  reference  types  that  do  not  contain  length  data  (see 
textDescriptor).  For  other  types  of  references,  this  field  is  ignored. 

styleDescriptor       Defines  the  type  of  reference  stored  in  styleRef. 


reflsPointer  $0000 
reflsHandle  $0001 
reflsResource    $0002 


styleRef  contains  a  pointer  to  a  TEFormat  structure 
styleRef  contains  a  handle  to  a  TEFormat  structure 
styleRef  contains  a  resource  ID  which  can  be  used  to 
access  a  buffer  containing  the  TEFormat  structure 
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styleRef  Reference  to  buffer  containing  style  information,  in  TEFormat 

structure  form.  If  this  field  is  set  to  NULL,  then  TEinsert  will  use  the 
first  defined  style  in  the  current  selection  for  the  record,  and  will 
ignore  styleDescriptor. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEScroll     $2522 

Scrolls  the  text  in  a  TextEdit  record.  Your  program  specifies  control  information  for  the 
scroll  and  the  TERecord  for  the  record.  TEScroll  then  updates  the  current  position  for 
the  record  accordingly. 

Parameters 

Stack  before  call 


Previous  contents 


scrollDescriptor 


vertAmount    - 


-    horzAmount    - 


teHandle 


Stack  after  call 


Word — Control  information  for  the  scroll  operation 
Long— Vertical  amount  to  scroll  (this  is  a  signed  value) 

Long— Horizontal  amount  to  scroll  (Must  be  set  to  0) 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


Errors 
C 


$2202 


<— SP 

teNotStarted 


TextEdit  has  not  been  started 


extern  pascal  void  TEScroll (vertAmount,  horzAmount, 
teHandle) ; 


Long 


vertAmount,  horzAmount,  teHandle; 
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scrollDescriptor      Defines  the  nature  of  the  scroll  operation,  and  the  use  of  and  units  for 
vertAmount  and  horzAmount: 

$0000  Scroll  to  absolute  text  position,  place  at  top  of  window.  The 

vertAmount  parameter  contains  the  offset  value  for  the  text 
character  to  place  at  the  top  of  the  TextEdit  display  window. 
The  horzAmount  parameter  is  ignored. 

$0001  Scroll  to  absolute  text  position,  center  in  window.  The 

vertAmount  parameter  contains  the  offset  value  for  the  text 
character  to  place  in  the  center  of  the  TextEdit  display  window. 
The  horzAmount  parameter  is  ignored. 

$0002  Scroll  to  line,  place  at  top  of  window.  The  vertAmount  parameter 

contains  a  line  number  specifying  which  text  line  to  place  at  the 
top  of  the  TextEdit  display  window.  The  horzAmount 
parameter  is  ignored. 

$0003  Scroll  to  line,  center  in  window.  The  vertAmount  parameter 

contains  a  line  number  specifying  which  text  line  to  center  in  the 
TextEdit  display  window.  The  horzAmount  parameter  is 
ignored. 

$0004  Scroll  to  absolute  unit  position,  place  at  top  of  window.  The 

vertAmount  parameter  contains  a  value  to  which  to  scroll  the  top 
of  the  TextEdit  window,  in  units  defined  by  the  value  of  the 
vertScrollAmount  field  of  the  TERecord  for  the  record.  The 
horzAmount  parameter  must  be  set  to  0. 

$0005  Scroll  to  relative  unit  position,  place  at  top  of  window.  The 

vertAmount  parameter  contains  a  value  to  add  to  contents  of 
the  vertScrollPos  field  of  the  TERecord  for  the  record,  in  units 
defined  by  the  value  of  the  vertScrollAmount  field  of  that 
TERecord.The  horzAmount  parameter  must  be  set  to  0. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TESetRuler     $2422 

Sets  the  ruler  for  a  TextEdit  record.  Your  program  specifies  the  new  ruler  definition,  in 
TERuier  format,  and  the  TERecord  for  the  record.  TESetRuler  then  sets  the  ruler  as 
specified,  and  reformats  all  text  in  the  record.  For  TextEdit  controls,  TESetRuler 
invalidates  the  entire  display  rectangle  (the  screen  will  be  redrawn  on  the  next  update 
event).  For  TextEdit  records  that  are  not  controls,  TESetRuler  redraws  the  screen. 

Parameters 

Stack  before  call 


Previous  contents 


rulerDescriptor 


rulerRef 


teHandle 


Word— Defines  type  of  reference  in  rulerRef 

Long— Reference  to  buffer  containing  new  TERuier  structure 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


$2202 


<— SP 
teNotStarted 


TextEdit  has  not  been  started 


extern  pascal  void  TESetRuler (rulerDescriptor, 
rulerRef,  teHandle) ; 


Word      rulerDescriptor; 
Long      rulerRef,  teHandle; 

rulerDescriptor      Defines  the  type  of  reference  stored  in  rulerRef. 

refisPointer  $0000  rulerRef  contains  a  pointer  to  a  buffer  containing  the 

TERuier  structure 
ref  isHandie  $0001  rulerRef  contains  a  handle  to  a  buffer  containing  the 

TERuier  structure 
ref  i sResource        $0002         rulerRef  contains  a  resource  ID  which  can  be  used  to 

access  a  buffer  containing  the  TERuier  structure 
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teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TESetSelection     $1D22 

Sets  the  current  selection  for  a  TextEdit  record.  Your  program  specifies  the  starting  and 
ending  text  byte  offsets  for  the  selection  and  the  TERecord  for  the  record. 
TESetSelection  then  updates  the  record  accordingly. 

If  the  ending  offset  value  is  less  than  the  starting  value,  TESetSelection  automatically 
swaps  them.  If  either  offset  is  beyond  the  end  of  the  text  for  the  record,  it  is  reset  to  the 
offset  for  the  last  character. 

Parameters 

Stack  before  call 


Previous  contents 


-    selectionStart 


-    selectionEnd    - 


teHandle 


Long— Starting  offset  value 

Long— Ending  offset  value 

Long — Handle  of  TERecord  in  memory;  NULL  for  active  record 

<— SP 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$2203 


<— SP 

teNotStarted 
telnvalidHandle 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 


teHandle 


extern  pascal  void  TESetSelection (selectionStart, 
selectionEnd,  teHandle) ; 

Pointer   selectionStart,  selectionEnd; 
Long      teHandle; 

Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TESetText     $0B22 

Replaces  the  text  in  a  TextEdit  record,  including  style  information,  with  supplied  text  and 
style  data.  Your  program  supplies  the  text  and  style  information,  along  with  the 
TERecord  for  the  TextEdit  record.  TESetText  then  replaces  any  existing  text  and  style 
information  in  the  record  with  the  supplied  data.  For  TextEdit  controls,  TESetText  then 
invalidates  the  entire  display  rectangle  (the  screen  will  be  redrawn  on  the  next  update 
event).  For  TextEdit  records  that  are  not  controls,  TESetText  redraws  the  screen 
immediately. 

Supplied  style  information  must  be  formatted  in  a  TEFormat  structure. 

Parameters 

Stack  before  call 


Previous  contents 


textDescriptor 


textRef 


textLength 


styleDescriptor 


styleRef 


teHandle 


Stack  after  call 


Previous  contents 


Errors 


Word— Defines  the  format  for  text  stored  at  textRef 
Long— Reference  to  the  input  text 

Long— Length  of  the  buffer  referred  to  by  textRef 
Word— Defines  the  type  of  reference  stored  in  styleRef 
Long— Reference  to  TEFormat  structure  defining  style 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


<— SP 


$2202    teNotStarted 
$2203    telnvalidHandle 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 


TERecord 

$2204        teinvaiidDescriptor  Invalid  descriptor  value  specified 
Memory  Manager  errors  Returned  unchanged 
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C  extern  pascal  void  TESetText (textDescriptor, 

textRef,  textLength,  styleDescriptor, 
styleRef ,  teHandle) ; 

Long      textRef,  textLength,  styleRef,  teHandle; 
Word      textDescriptor,  styleDescriptor; 

textDescriptor        Defines  the  format  of  the  new  text  for  the  record,  and  the  type  of 
reference  stored  in  textRef. 

Reserved  bits  5-16     Must  be  set  to  0 

refFormat  bits  3-4       Defines  the  type  of  reference  stored  in  textRef. 

00  -  textRef  'is  a  pointer  to  the  text;  textLength 
contains  the  length  of  the  buffer  (in  bytes) 

01  -  textRef  is  a  handle  to  the  text;  textLength  is 
ignored 

10  -  textRef  'is  a  resource  ID  for  the  text;  textLength  is 
ignored 

11  -  Invalid  value 
dataFormat                 bits  0-2      Defines  the  format  of  the  text: 

000  -  Text  is  a  Pascal  string  (resource  type  of 
rPString) 

001  -  Text  is  a  C  string  (resource  type  of  rcstring) 

010  -  Text  is  a  Class  1  GS/OS  input  string  (resource 
type  of  rdlnputString) 

011  -  Text  is  a  Class  1  GS/OS  output  string  (resource 
type  of  rCl  Output  St  ring) 

100  -  Text  is  formatted  for  input  to  LineEdit 
TextBox2  tool  call  (resource  type  of 
rTextBox2)— see  Chapter  10,  "LineEdit  Tool  Set," 
in  the  Toolbox  Reference  for  details;  style  data  in  the 
text  overrides  that  specified  by  styleRef 

101  -  Text  is  an  unformatted  text  block  (resource 
type  of  rText) 

110  -  Invalid 

111  -  Invalid 

textLength  Defines  the  length  of  the  output  buffer  referenced  by  textRef  This 

field  is  only  valid  for  reference  types  that  do  not  contain  length  data 
(see  textDescriptor).  For  other  types  of  references,  this  field  is  ignored. 
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styleDescriptor       Defines  the  type  of  reference  stored  in  styleRef. 


ref IsPointer 
reflsHandle 
ref IsResource 


styleRef 


teHandle 


$0000         styleRef 'contains  a  pointer  to  the  TEFormat  structure 
$0001         styleRef  contains  a  handle  to  the  TEFormat  structure 
$0002         styleRef  contains  a  resource  ID  which  can  be  used  to 
access  the  TEFormat  structure 


Reference  to  style  information  for  the  new  text,  in  TEFormat 
structure  form.  If  this  field  is  set  to  NULL,  then  TESetText  uses  the 
first  style  encountered  in  the  existing  text  for  the  record. 

Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEStyleChange     $1F22 

Changes  the  style  information  for  the  current  selection  in  a  TextEdit  record.  Your 
program  specifies  the  style  information  and  the  TERecord  for  the  record.  TEStyleChange 
then  applies  that  new  information  to  all  the  styles  in  the  current  selection.  If  there  is  no 
current  selection,  then  the  new  style  applies  to  the  null  style  record,  which  defines  style 
information  for  newly  inserted  text. 

Parameters 

Stack  before  call 


Previous  contents 


flags 


stylePtr 


teHandle 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$2205 


Word — Control  flag  for  applying  style  data  from  TEStyie 
Long— Pointer  to  TEStyie  structure 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


<— SP 

teNotStarted 
telnvalidFlag 


TextEdit  has  not  been  started 
Specified  flag  word  is  invalid 


extern  pascal  void  TEStyleChange {flags,  stylePtr, 
teHandle) ; 

Word      flags; 
Pointer    stylePtr; 
Long      teHandle; 
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flags 
Reserved 

fReplaceFont 


fReplaceSize 


Indicates  which  portions  of  the  TEStyle  structure  pointed  to  by 
stylePtr  are  relevant: 

bits7— 1 5      Must  be  set  to  0 

bit  6  Controls  use  of  font  family  defined  by  font  id  field 

of  TEStyle  structure: 

1  -  Replace  the  font  family  for  all  styles  in  the  current 

selection 

0  -  Do  not  change  font  family 

bit  5  Controls  use  of  font  size  defined  by  font  id  field  of 

TEStyle  structure 

1  -  Replace  the  font  size  for  all  styles  in  the  current 
selection 

0  -  Do  not  change  font  size 


fReplaceForeColor 


bit  4 


fReplaceBackColor 


bit  3 


fReplaceUserData  bit  2 


fReplaceAttributes 

bit  1 


Controls  use  of  foreColor  field  Of  TEStyle 

structure: 

1  -  Replace  the  foreground  color  for  all  styles  in  the 

current  selection 

0  -  Do  not  change  the  foreground  color 

Controls  use  of  backColor'field  of  TEStyle 
structure: 

1  -  Replace  the  background  color  for  all  styles  in  the 
current  selection 

0  -  Do  not  change  the  background  color 
Controls  the  use  of  the  userData  field  of  the 
TEStyle  structure: 

1  -  Replace  the  userData  field  for  all  styles  in  the 
current  selection  with  that  in  the  supplied  TEStyle 
structure 

0  -  Do  not  change  userData  field 

Controls  use  of  font  attributes  defined  by  the 
fontiD  field  of  TEStyle  structure: 

1  -  Replace  the  font  attributes  for  all  styles  in  the 
current  selection 

0  -  Do  not  change  font  attributes 
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f SwitchAttributes 

bit  0  Controls  attribute  switching: 

1  -  If  the  entire  selection  contains  the  font  attributes 
specified  by  the  TEStyle  structure  font  id  field, 
then  these  attributes  are  removed  from  the  selection; 
otherwise,  the  specified  attributes  are  added  to 
those  already  defined  for  the  selection  (note  that  the 
attributes  are  considered  together,  not  individually) 
0  -  Perform  no  attribute  switching 

♦  Note:  The  f  ReplaceAttributes  and  f  SwitchAttributes  flags  are  mutually 
exclusive.  If  both  flags  are  set  to  1,  TEStyieChange  returns  a  teinvaiidFiag 
error  code. 


stylePtr  Points  to  a  formatted  te  style  structure  containing  the  style 

elements  that  are  to  be  applied  to  the  current  selection.  The  flags 
parameter  indicates  which  portions  of  this  TEStyle  structure 
contain  valid  data. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEUpdate    $1222 

Redraws  the  screen  for  a  TextEdit  record.  Your  program  specifies  the  TERecord  for  the 
record.  TEUpdate  then  redraws  the  text  for  the  record.  Only  that  portion  of  the  screen 
that  must  be  redrawn  is  affected. 

Your  program  should  issue  this  call  after  the  Window  Manager  Beginupdate  call,  and 
before  an  Endupdate  call.  Issue  this  call  separately  for  each  TextEdit  record  in  the 
window.  TextEdit  returns  very  quickly  if  no  redraw  is  required. 

If  your  program  uses  TextEdit  controls,  use  the  ControlManager  DrawControis  tool  call, 
rather  than  this  one. 


Parameters 

Stack  before  call 

Previous  contents 

teHandle 

Long— Handle  of  TERecord  in  memory 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  $2202 

teNotstarted               TextEdit  has  not  been  started 

$2203 

teinvaiidHandie          teHandle  does  not  refer  to  a  valid 

TERecord 

extern  pascal  void  TEUpdate (teHandle) ; 
Long      teHandle; 
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TextEdit  summary 

This  section  summarizes  the  constants,  data  structures,  and  error  codes  used  by  the 
Resource  Manager. 


Table  49-1       TextEdit  constants 


Name 

Value 

Description 

Justification 

values 

leftJust 
rightJust 
centerJust 
fullJust 

$0000 
$FFFF 
$0001 
$0002 

Left  justify  all  text 

Right  justify  all  text 

Center  all  text 

Fully  justify  all  text  (both  left  and  right 

margins) 

TERuler  flags  field  values 

fShowInvisibles  $2000 

fEqualLineSpacing  $4000 

TERuler  tabType  field  values 

noTabs  $0000 

stdTabs  $0001 


absTabs 


$0002 


TEParamBlock  flags  field  values 


fCtllnvis 
fRecordDirty 


$0080 
$0040 


Show  invisible  characters  (space,  tab, 

return) 

TextEdit  uses  maximum  line  spacing 

for  every  line  in  the  block 


No  tabs  defined— tabType  is  last 
field  in  TERuler  structure 
Tabs  every  tabTerminator  pixels — 
tabTerminator  is  last  field  in  the 
TERuler  Structure;  theTabs  is 

omitted 

Tabs  at  absolute  locations  specified 

by  theTabs  array 


Controls  visibility  of  the  record 
Indicates  whether  text  or  style  data 
have  changed  since  the  last  save 
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TEParamBlockmoreFlags  field  values 


fCtlTarget 

$8000 

fCtlCanBeTarget 

$4000 

fCtlWantsEvents 

$2000 

fCtlProcRefNotPtr 

$1000 

fTellAboutGrow 

$0800 

fCtllsMultiPart 

$0400 

colorDescriptor 

$000C 

styleDescriptor 


$0003 


TEParamBlock  textFlags  field  values 


fNotControl 
fSingleFormat 

fSingleStyle 

fNoWordWrap 

fNoScroll 

fReadOnly 

fSmartCutPaste 

fTabSwitch 

fDrawBounds 

fColorHilight 
fGrowRuler 


$80000000 
$40000000 

$20000000 
$10000000 
$08000000 
$04000000 
$02000000 

$01000000 

$00800000 

$00400000 
$00200000 


fDisableSelection  $00100000 

fDrawInactiveSelection      $00080000 


Record  is  target  of  user  keystrokes 

Record  can  be  target  of  user 

keystrokes— must  be  set  to  1 

Must  be  set  to  1 

Must  be  set  to  1 

Record  wants  to  know  when  the  user 

changes  the  window  size 

Must  be  set  to  1 

Indicates  type  of  reference  in 

colorRef 

Indicates  type  of  reference  in 

styleRef 


TextEdit  Record  is  not  a  control 
Only  one  ruler  is  allowed  for  record- 
must  be  set  to  1 

Only  one  style  is  allowed  for  record 
No  word  wrap  is  performed 
The  text  cannot  scroll 
Text  cannot  be  edited 
Record  supports  intelligent  cut  and 
paste 

Tab  key  switches  user  to  next  TextEdit 
record  on  the  screen 
TextEdit  draws  a  box  around  text, 
inside  the  bounding  rectangle 
Use  color  table  for  highlighting 
Adjust  right  margin  whenever  the  user 
changes  the  window  size 
User  cannot  select  or  edit  text 
TextEdit  displays  a  box  around  an 
inactive  selection 
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Table  49-2       TextEdit  data  structures 


Name                             Offset/Value 

Type 

Description 

TECol or Table 

contentColor       $0000 

Word 

Color  for  inside  of  bounds  rectangle 

outlineColor       $0002 

Word 

Color  for  outline  drawn  around  text 

hilightForeColor 

$0004 

Word 

Foreground  color  for  highlighted  text 

hilightBackColor 

$0006 

Word 

Background  color  for  highlighted  text; 
also  used  for  caret 

vertColorDescriptor 

$0008  Word 

vertColorRef       $000A  LongWord 


horzColorDescriptor 

$000E  Word 


horzColorRef       $0010  LongWord 

growColorDescriptor 

$0014  Word 

growColorRef       $0016  LongWord 


Specifies  type  of  reference  in 

vertColorRef 

Reference  to  color  table  for  vertical 

scroll  bar 

Specifies  type  of  reference  in 

horzColorRef 

Reference  to  color  table  for  horizontal 

scroll  bar 

Specifies  type  of  reference  in 
growColorRef 

Reference  to  color  table  for  size  box 


♦   Note:  All  of  the  bits  in  each  TECoiorTabie  color  word  are  significant.  TextEdit 
forms  color  patterns  by  replicating  the  appropriate  color  word  the  appropriate 
number  of  times  to  form  a  QuickDraw  n  pattern. 
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TEFormat  (format  structure) 

$0000  Word 


version 


rulerListLength 


$0002  LongWord 


theRulerList   $0006 
styleListLength 

theStyleList 
numberOf Styles 
theStyles 


TERuler 
LongWord 

TEStyle 

LongWord 

Styleltem 


Version  number  for  format  structure- 
value  must  be  $0000 

Size,  in  bytes,  of 

theRulerList  array 

Array  of  TERuler  structures 

Size,  in  bytes,  of  theStyleList 

array 

Array  of  TEStyle  structures 

Number  of  entries  in  theStyles  array 

Array  of  style  it  em  structures 
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TEParamBiock  (parameter  block  for  creating  TextEdit  structures) 


pCount 

$0000 

Word 

Number  of  parameters  to  follow— 
values  range  from  7  through  23 

ID 

$0002 

LongWord 

Application  assigned  ID  for  record 

rect 

$0006 

Rect 

Bounding  rectangle  for  entire  TextEdit 
record,  including  scroll  bars  and 
outlines 

procRef 

$000E 

LongWord 

Must  be  set  to  $85000000 

flags 

$0012 

Word 

Control  flags 

moreFlags 

$0014 

Word 

More  control  flags 

refCon 

$0016 

LongWord 

Reserved  for  application  use 

textFlags 

$001A 

LongWord 

TextEdit  control  flags 

indentRect 

$001E 

Rect 

Specifies  bounding  rectangle  for  text 
in  TextEdit  record 

vertBar 

$0026 

Handle 

Handle  to  vertical  scroll  bar 

vert Amount 

$002A 

Word 

Number  of  pixels  to  scroll  per  click  on 
vertical  scroll  arrows 

horzBar 

$002C 

Handle 

Reserved— must  be  set  to  NULL 

horzAmount 

$0030 

Word 

Reserved— must  be  set  to  $0000 

styleRef 

$0032 

LongWord 

Reference  to  initial  style  information 
for  record 

textDescriptoi 

:  $0036 

Word 

Defines  format  of  textRef 

textRef 

$0038 

LongWord 

Reference  to  initial  text  for  record 

textLength 

$003C 

LongWord 

Length  of  text  referred  to  by  textRef 

maxChars 

$0040 

LongWord 

Maximum  number  of  characters 
allowed  in  record 

maxLines 

$0044 

LongWord 

Must  be  set  to  NULL 

maxCharsPerLine 

$0048 

Word 

Must  be  set  to  NULL 

maxHeight 

$004A 

Word 

Must  be  set  to  NULL 

colorRef 

$004C 

LongWord 

Reference  to  the  TECoiorTabie  for 
the  record 

drawMode 

$0050 

Word 

QuickDraw  II  text  mode 

filterProcPtr 

$0052 

Pointer 

Pointer  to  filter  routine  for  the  record 

TERecord  (control  structure  for  TextEdit 

records) 

ctrlNext 

$0000 

Handle 

Handle  to  next  control  in  control  list 

inPort 

$0004 

Pointer 

Pointer  to  GrafPort  for  TextEdit 

boundsRect 


$0008 


Rect 


record 

Bounding  rectangle  for  record 
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ctrlFlag 

$0010 

Byte 

Low-order  byte  from  TEParamBiock 
flags  field 

ctrlHilite 

$0011 

Byte 

Reserved 

lastErrorCode 

$0012 

Word 

Last  error  generated  by  TextEdit 

ctrlProc 

$0014 

LongWord 

Always  set  to  $85000000 

ctrlAction 

$0018 

LongWord 

Reserved 

filterProc 

$001C 

Pointer 

Pointer  to  filter  procedure  for  the 
record 

ctrlRefCon 

$0020 

LongWord 

Reserved  for  application 

colorRef 

$0024 

LongWord 

Reference  to  TECoiorTabie  for 
record 

textFlags 

$0028 

LongWord 

TEParamBiock  textFlags  field 

text Length 

$002C 

LongWord 

Length,  in  bytes,  of  text  in  record 

blockList 

$0030 

TextList 

TextList  structure  describing  text 
for  the  record 

ctrllD 

$0038 

Long 

Application-assigned  ID  for  the  record 

ctrlMoreFlags 

$003C 

Word 

TEParamBiock  moreFlags  field 

Ctrl Version 

$003E 

Word 

Reserved 

viewRect 

$0040 

Rect 

Bounding  rectangle  for  text  on  screen 

totalHeight 

$0048 

LongWord 

Total  height  of  the  text  for  the  record, 
in  pixels 

lineSuper 

$004C 

SuperHandle 

i  Root  reference  for  text  in  record 

styleSuper 

$0058 

SuperHandle 

i  Root  reference  for  styles  in  record 

styleList 

$0064 

Handle 

Handle  to  list  of  unique  styles 

rulerList 

$0068 

Handle 

Handle  to  list  of  rulers 

lineAtEndFlag 

$006C 

Word 

Indicates  whether  last  character  was  a 
line  break 

selectionStart 

.  $006E 

LongWord 

Starting  text  offset  for  current 
selection 

selectionEnd 

$0072 

LongWord 

Ending  text  offset  for  current  selection 

selectionActive 

$0076 

Word 

Indicates  whether  selection  is  active 

selectionState 

■  $0078 

Word 

Indicates  whether  selection  is  on 
screen 

caretTime 

$007A 

LongWord 

Tick  count  for  caret  blink 

nullStyleActive 

$007E  Word 

nullStyle  $0080  TEStyle 

topTextoffset    $008C  LongWord 


Indicates  whether  null  style  is  to  be 

used 

Style  definition  for  null  style 

Offset  into  record  text  corresponding 

to  top  of  screen 
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topTextVPos 


$0090 


Word 


vertScrollBar 

$0092 

Handle 

vertScrollPos 

$0096 

LongWord 

vertScrollMax 

$009A 

LongWord 

vertScrollAmount 

$009E 

Word 

horzScrollBar 

$00A0 

Handle 

horzScrollPos 

$00A4 

LongWord 

horzScrollMax 

$00A8 

LongWord 

horzScrollAmount 

$00AC 

Word 

growBoxHandle 
maximumChars 

$00AE 
$00B2 

Handle 
LongWord 

maximumLines        $00Bo 


LongWord 


maxCharsPerLine 

$00BA 

Word 

maximumHeight 

$00BC 

Word 

textDrawMode 

$00BE 

Word 

wordBreakHook 

$00C0 

Pointer 

wordWrapHook 
keyFilter 
theFilterRect 
theBufferVPos 

$00C4 
$00C8 
$00CC 
$00D4 

Pointer 
Pointer 
Rect 
Word 

theBufferHPos 

$00D6 

Word 

theKeyRecord 

$00D8 

KeyRecord 

cachedSelcOffset 

$00E6 

LongWord 

Difference  between  top  of  text  and 
topmost  scroll  position 
Handle  of  vertical  scroll  bar 
Current  vertical  scroll  position 
Maximum  allowable  vertical  scroll  from 
top  of  text 

Number  of  pixels  to  scroll  on  each 

vertical  arrow  click 

Handle  of  horizontal  scroll  bar  (not 

supported) 

Current  horizontal  scroll  position  (not 

supported) 

Maximum  allowable  horizontal  scroll 

from  left  boundary  (not  supported) 

Number  of  pixels  to  scroll  on  each 
horizontal  arrow  click  (not  supported) 
Handle  to  the  Size  box  control 
Maximum  number  of  characters 
allowed  in  the  text 
Maximum  number  of  lines  allowed  in 
the  text  (not  supported) 

Maximum  number  of  characters 

allowed  in  a  line  (not  supported) 

Maximum  text  height,  in. pixels  (not 

supported) 

QuickDraw  II  drawing  mode  for  the 

text 

Pointer  to  routine  to  handle  word 

breaks 

Pointer  to  routine  to  handle  word  wrap 

Pointer  to  keystroke  filter  routine 

Rectangle  for  generic  filter  procedure 

Vertical  component  of  current  position 

for  generic  filter  procedure 

Horizontal  component  of  current 

position  for  generic  filter  procedure 

Parameters  for  keystroke  filter  routine 

Text  offset  for  cached  caret  position 
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cachedSelcVPos 

$00EA 

Word 

Vertical  component  of  cached  caret 
position 

cachedSelcHPos 

$00EC 

Word 

Horizontal  component  of  cached  caret 
position 

mouseRect 

$00EE 

Rect 

Bounding  rectangle  for  mouse  events 

mouseTime 

$00F6 

LongWord 

Tick  count  value  when  mouse  button 
was  last  released 

mouseKind 

$00FA 

Word 

Kind  of  last  click 

lastClick 

$00FC 

Point 

Location  of  last  mouse  click 

savedHPos 

$0100 

Word 

Saved  horizontal  position  for  up  and 
down  arrows 

anchorPoint 

$0102 

Long 

Anchor  point  for  current  selection 

♦  Note:  TextEdit  maintains  fields  beyond  anchorPoint.  Applications  should  never 
access  these  fields  or  attempt  to  save  the  state  of  a  TextEdit  record  by  writing  and 
reading  the  public  fields  documented  here. 


TERuier  (ruler  structure) 

leftMargin  $0000 


Word 


left Indent 

$0002 

Word 

rightMargin 

$0004 

Word 

just 

$0006 

Word 

extraLS 

$0008 

Word 

flags 

$000A 

Word 

userData 

$0O0C 

LongWord 

tabType 

$0010 

Word 

theTabs 

$0012 

Tabltem 

tabTerminator 

Word 

te  style  (style  description  structure) 


fontID 

$0000 

LongWord 

foreColor 

$0004 

Word 

backColor 

$0006 

Word 

userData 

$0008 

LongWord 

Left  indent  pixel  count  for  all  lines 

except  those  that  start  paragraphs 

Left  indent  pixel  count  for  lines  that 

start  paragraphs 

Right  text  boundary,  measured  from 

left  edge  of  text  rectangle 

Text  justification  flag 

Spacing  between  lines  (in  pixels) 

Control  flags  for  the  ruler 

Reserved  for  application  use 

Indicates  type  of  tabs  used 

Array  of  Tabitems,  one  for  each 

absolute  tab  stop 

Either  the  spacing  for  standard  tabs  or 

a  flag  terminating  theTabs  array 


FontID  for  text  using  this  style 
Foreground  color  for  the  style 
Background  color  for  the  style 
Reserved  for  application  use 
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KeyRecord 

theChar 

$0000 

Word 

Character  value  to  translate 

theModifiers 

$0002 

Word 

Modifier  key  state  bit  flag  (see 
Chapter  7,  "Event  Manager,"  for 
information  on  key  modifiers) 

thelnputHandle 

$0004 

Handle 

Handle  to  character  in  text 

cursorOff set 

$0008 

LongWord 

New  cursor  location 

theOpCode 

$0O0C 

Word 

Operation  code  for  key  filter  routine 

styieitem  (style  reference  structure) 

length  $0000  LongWord 

offset  $0004  LongWord 


Number  of  text  characters  using  the 

style 

Byte  offset  into  theStyleList  to 

entry  that  defines  the  style  for  this  text 


SuperBlock 

nextHandle 
prevHandle 

textLength 


the Items 


$0000  Handle  Handle  to  next  SuperBlock  in  list 

$0004  Handle  Handle  to  previous  SuperBlock  in 

list 
$0008  LongWord         Number  of  bytes  of  text  for  this 

SuperBlock 
$000C  LongWord        Reserved 

$0010  Superitem      Array  of  Superitems  for  this  block 


SuperHandle 

cachedHandle  $0000  Handle 

cachedOffset  $0004  LongWord 

cachedlndex  $0008  Word 

itemsPerBlock  $000A  Word 


Handle  to  the  current  SuperBlock 
Text  offset  to  the  start  of  the  current 

SuperBlock 

Index  value  for  current  SuperBlock 

Number  of  superitems  per 

SuperBlock 


Superitem 

length  $0000  LongWord 

data  $0004  LongWord 


Number  of  bytes  of  text  for  this 

Superitem 

Data  for  the  Superitem 
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Tabitem  (tab  stop  descriptor) 


tabKind 

$0000 

Word 

Must  be  set  to  $0000 

tabData 

$0002 

Word 

Pixel  offset  to  the  tab  stop  from  left 
boundary  of  text  rectangle 

TextBlock 

nextHandle 

$0000 

Handle 

Handle  to  next  TextBlock  in  list 

prevHandle 

$0004 

Handle 

Handle  to  previous  TextBlock  in  list 

textLength 

$0008 

LongWord 

Number  of  bytes  of  text  in  theText 

flags 

$000C 

Word 

Reserved 

$000E 

Word 

Reserved 

theText 

$0010 

Byte 

textLength  bytes  of  text 

TextLiat 

cachedHandle 

$0000 

Handle 

Handle  to  the  current  TextBlock 

cachedOffset 

$0004 

LongWord 

Text  offset  to  the  start  of  the  current 

TextBlock 
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Table  49-3       TextEdit  error  codes 


Code 


Name 


Description 


$2201 

teAlreadyStarted 

$2202 

teNotStarted 

$2203 

telnvalidHandle 

$2204 

telnvalidDescriptor 

$2205 

telnvalidFlag 

$2206 

telnvalidPCount 

$2207 

Reserved 

$2208 

teBufferOverflow 

$2209 


$220A 

$220B 
$220C 


telnvalidLine 


telnvalidCall 

telnvalidParameter 
teInvalidTextBox2 


TextEdit  has  already  been  started 

TextEdit  has  not  been  started 

The  teHandle  parameter  does  not  refer 

to  a  valid  TERecord 

Invalid  descriptor  value  specified 

Specified  flag  word  is  invalid 

Invalid  parameter  count  value 

specified 

Reserved 

The  output  buffer  was  too  small  to 

accept  all  data 

Starting  line  value  is  greater  than  the 

number  of  lines  in  the  text  (can  be 

interpreted  as  end-of-file  in  some 

circumstances) 

This  call  is  not  allowed  for  the  supplied 

TERecord 

A  passed  parameter  was  invalid 

The  TextBox2  format  codes  were 
inconsistent 
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Chapter  50  Text  Tool  Set  Update 


This  chapter  documents  new  features  of  the  Text  Tool  Set.  The  complete 
reference  to  the  Text  Tool  Set  is  in  Volume  2,  Chapter  23  of  the 
Apple  IIGS  Toolbox  Reference. 
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New  features  in  the  Text  Tool  Set 

The  following  information  describes  new  features  in  this  version  of  the  Text  Tool  Set. 

The  Text  Tool  Set  now  supports  the  Slot  Arbiter.  All  set  device  calls  (such  as 
SetOutputDevice,  setmputDevice,  and  so  forth)  accept  slot  numbers  1  through  7 
or  9  through  15.  Previously,  the  external  slots,  slots  9  through  15,  were  not  valid  for  these 
calls.  If  your  application  specifies  an  external  slot,  the  Text  Tool  Set  will  route  the  calls  as 
appropriate.  If  your  application  specifies  a  slot  from  1  through  7,  the  Text  Tool  Set 
determines  whether  the  slot  is  internal  or  external,  and  routes  the  calls  to  the  appropriate 
firmware. 

Note  that  all  get  device  calls  still  return  slot  numbers  in  the  range  from  1  through  7,  in  order 
to  maintain  compatability  with  existing  code. 
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Chapter  51   Tool  Locator  Update 


This  chapter  documents  new  features  of  the  Tool  Locator.  The  complete 
reference  to  the  Tool  Locator  is  in  Volume  2,  Chapter  24  of  the 
Apple  UGS  Toolbox  Reference. 
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New  features  in  the  Tool  Locator 

This  section  explains  new  features  of  the  Tool  Locator. 

■  The  Tool  Locator  uses  a  new  algorithm  to  load  tools  from  disk.  It  will  load  tools  from 
disk  only  if  it  cannot  find  a  tool  in  ROM  with  a  version  number  as  high  as  the  requested 
version.  The  Tool  Locator  makes  no  assumptions  about  which  tools  are  in  ROM  and 
which  are  on  the  system  disk. 

For  every  tool  that  is  to  be  loaded,  the  Tool  Locator  makes  a  version  call.  If  the  version 
call  returns  an  error  because  the  tool  is  not  present,  or  the  resulting  version  number  is 
too  low,  then  the  tool  is  loaded  from  the  system  disk. 

■  The  Tool  Locator  no  longer  unloads  all  RAM-based  tools  every  time  TLShutDown  is 
called.  Instead,  it  returns  the  system  to  a  default  state,  set  by  a  new  call  in  the  Tool 
Locator,  setDef  auitTPT.  This  call  can  make  any  collection  of  RAM  and  ROM  tools 
the  default  state.  The  system  returns  to  the  default  state  when  TLShutdown  is  called. 


Tool  set  startup  and  shutdown 

The  Tool  Locator  now  provides  calls  that  automatically  start  and  stop  specified  tool  sets 
in  the  correct  order.  These  calls,  startupToois  and  shutDownToois,  are  documented 
in  "New  Tool  Locator  calls"  later  in  this  chapter. 

The  startupToois  call  performs  the  following  steps  during  startup  processing: 

1)  Starts  the  Resource  Manager 

2)  Opens  the  resource  fork  for  the  current  application 

3)  Obtains  memory  for  the  application's  direct  page 

4)  Starts  the  tools  specified  in  the  input  startstop  record;  updates  the  startstop 
record  as  appropriate 

5)  Returns  the  startstop  record  reference  to  the  calling  program 

Your  application  must  pass  this  returned  startstop  record  reference  to 
ShutDownToois  at  tool  shutdown  time. 
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startupToois  sets  some  tool  set  default  values  for  you.  If  these  value  are  not 
appropriate  for  your  application,  you  should  change  them  by  issuing  the  appropriate  tool 
calls  after  startupToois  has  returned: 

QuickDraw  n  Started  with  the  video  mode  from  the  input 

startstop  record— the  QDStartup  maxWidth 
parameter  is  set  to  160  bytes. 

System  calls  waitcursor;  your  application  must 
change  the  cursor  to  an  arrow  before  accepting  user 
input. 

Queue  size  set  to  20,  maximum  mouse  clamp  set  to 
either  320  or  640,  depending  upon  the  video  mode 
specified  in  the  startstop  record. 

Update  rate  set  to  0  (use  default  Note  Synthesizer  rate), 
increment  set  to  20,  and  interrupts  have  been  disabled 
(the  system  calls  stopints).  Your  program  must  enable 
interrupts  with  startints.  The  Note  Sequencer  will 
automatically  start  the  Sound  Tool  Set  and  the  Note 
Synthesizer,  if  you  have  not  included  them  in  your 
startstop  record. 

shutDownToois  performs  the  following  steps  during  tool  set  shutdown: 

1)  Shuts  down  tools  specified  in  input  startstop  record 

2)  Disposes  of  handle  to  direct  page 

3)  Disposes  of  handle  to  startstop  record  (unless  pointer  was  passed) 

4)  Shutsdown  the  Resource  Manager 


QuickDraw  II  Auxiliary 


Event  Manager 


Note  Sequencer 
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Both  these  calls  require  that  your  application  format  a  tool  start  stop  record.  That 
record  is  defined  as  follows: 


Figure  51-1      Tool  set  StartStop  record 


$00 

—                flags                — 

Word— Flag  word— must  be  set  to  0 

$02 

—            videoMode            — 

Word— Video  mode  for  QuickDraw  II 

$04 

—           resFilelD           — 

Word— Set  by  StartUpTools 

$06 

—         dPageHandle         — 

Long— Set  by  StartUpTools 

$0A 

—             numTools            — 

Word— Number  of  entries  in  toolAi 

$0C 

tool Array 

numTool  s  ToolSpec  records 

videoMode 


resFilelD 


dPageHandle 


Defines  the  video  mode  for  QuickDraw  n.  See 

Chapter  16,  "QuickDraw  II,"  in  the  Toolbox  Reference  for  valid  values. 

The  StartUpTools  call  sets  this  field.  snutDownToois  requires  it 
as  input. 

The  StartUpTools  call  sets  this  field.  shutDownToois  requires  it 
as  input. 
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tooiArray  Each  entry  defines  a  tool  set  to  be  started.  The  numToois  field 

specifies  the  number  of  entries  in  this  array.  Each  entry  is  formatted  as 
follows: 


$00 
$02 


tooiNumber       -   Word— Tool  set  identifier 


-       minversion       -   Word— Minimum  acceptable  tool  set  version 


tooiNumber        Specifies  the  tool  set  to  be  loaded  Valid  tools  set  numbers  are 
listed  in  Table  51-1. 

tooiversion      Specifies  the  minimum  acceptable  version  for  the  tool  set.  See 
Chapter  24,  "Tool  Locator,"  in  the  Toolbox  Reference  for  the 
format  of  this  field. 
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Tool  set  numbers 

Table  51-1  lists  the  tool  set  numbers  for  all  tool  sets  supported  by  the  startupToois 
and  shutDownToois  calls. 


Table  51-1        Tool  set  numbers 


Tool  set  number  Tool  set  name 


$01 

#01 

Tool  Locator 

$02 

#02 

Memory  Manager 

$03 

#03 

Miscellaneous  Tool  Set 

$04 

#04 

QuickDraw  II 

$05 

#05 

Desk  Manager 

$06 

#06 

Event  Manager 

$07 

#07 

Scheduler 

$08 

#08 

Sound  Tool  Set 

$09 

#09 

Apple  Desktop  Bus  Tool  Set 

$0A 

#10 

SANE  Tool  Set 

$0B 

#11 

Integer  Math  Tool  Set 

$0C 

#12 

Text  Tool  Set 

$0D 

#13 

Reserved  for  internal  use 

$0E 

#14 

Window  Manager 

$0F 

#15 

Menu  Manager 

$10 

#16 

Control  Manager 

$11 

#17 

System  Loader 

$12 

#18 

QuickDraw  II  Auxiliary 

$13 

#19 

Print  Manager 

$14 

#20 

LineEdit  Tool  Set 

$15 

#21 

Dialog  Manager 

$16 

#22 

Scrap  Manager 

$17 

#23 

Standard  File  Operations  Tool  Set 

$18 

#24 

Not  available 

$19 

#25 

Note  Synthesizer 

$1A 

#26 

Note  Sequencer 

$1B 

#27 

Font  Manager 

$1C 

#28 

List  Manager 
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$1D 

#29 

Audio  Compression  (ACE) 

$1E 

#30 

Resource  Manager 

$20 

#32 

MIDI  Tool  Set 

$22 

#34 

TextEdit  Tool  Set 
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Tool  set  dependencies 

Although  startupToois  handles  the  order  of  tool  startup  for  you,  it  does  not  manage 
tool  set  dependencies.  It  is  your  responsibility  to  specify  all  required  tool  sets  in  order  to 
ensure  correct  system  operation.  Table  51-2  documents  current  tool  set  dependencies. 


Table  51-2       Tool  set  dependencies 


Tool  set  and  number 


Depends  upon 


Tool  Locator(#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 

QuickDraw  II  (#04) 


Desk  Manager  (#05) 


Event  Manager  (#06) 
Scheduler  (#07) 
Sound  Tool  Set  (#08) 


Apple  Desktop  Bus  (#09) 
SANE  Tool  Set  (#10) 


No  dependencies;  always  started  first 
Tool  Locator  (#01) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  n  (#04) 
Event  Manager  (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
LineEdit  (#20) 
Dialog  Manager  (#21) 
Scrap  Manager  (#22) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Tool  Locator  (#01) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
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Integer  Math  Tool  Set  (#11) 
Text  Tool  Set  (#12) 
Window  Manager  (#14) 


Menu  Manager  (#15) 


Control  Manager  (#16) 


Tool  Locator  (#01) 
Tool  Locator  (#01) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  n  (#04) 
Event  Manager  (#06) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
LineEdit  (#20) 
Font  Manager  (#27) 
Resource  Manager  (#30) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  H  (#04) 
Event  Manager  (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Resource  Manager  (#30) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  II  (#04) 
Event  Manager (#06) 
Window  Manager  (#14) 
Menu  Manager  (#15) 
Resource  Manager  (#30) 


For  AlertWindow  call 
For  AlertWindow  call 
Only  if  you  use 
resources 


Only  if  you  use 
resources 


Only  if  you  use 
resources  or  icon 
buttons 


♦  Note.  You  should  consider  the  Window,  Control,  and  Menu  managers  as  one  unit,  and 
always  start  them  together  and  in  that  order. 


System  Loader  (#17) 


Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
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QuickDraw  II  Auxiliary  (#18) 


Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  II  (#04) 
Font  Manager (#27) 


♦   Note.  QuickDraw  II  Auxiliary  uses  the  Font  Manager  in  the  picture  drawing  routines. 
For  proper  operation,  you  should  start  the  Font  Manager  before  using  the  QuickDraw 
n  Auxiliary  picture  routines;  however,  the  picture  routines  will  not  fail  if  the  Font 
Manager  is  not  present. 


Print  Manager  (#19) 


LineEdit  Tool  Set  (#20) 


Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  II  (#04) 
QuickDraw  II  Auxiliary  (#18) 
Event  Manager  (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
LineEdit  (#20) 
Dialog  Manager  (#21) 
List  Manager  (#28) 
Font  Manager  (#27) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  n  (#04) 
Event  Manager (#06) 
QuickDraw  n  Auxiliary  (#18) 
Scrap  Manager  (#22) 
Font  Manager  (#27) 


For  Text2  items  only 
For  Text  2  items  only 
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Dialog  Manager  (#21) 


Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  II  (#04) 
Event  Manager  (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
QuickDraw  II  Auxiliary  (#18) 
LineEdit  (#20) 
Font  Manager  (#27) 


For  Text2  items  only 
For  Text2  items  only 


♦   Note-.  LineEdit  and  Dialog  Manager  require  Font  Manager  and  QuickDraw  n  Auxiliary  if 
you  use  LETextBox2  or  LongstatText2  which  require  any  font  styling  (for 
example,  outfine,  boldface,  and  so  on). 


Scrap  Manager  (#22) 
Standard  File  Tool  Set  (#23) 


Note  Synthesizer  (#25) 


Note  Sequencer  (#26) 


Tool  Locator  (#01) 
Memory  Manager  (#02) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  II  (#04) 
Event  Manager (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
LineEdit  (#20) 
Dialog  Manager  (#21) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Sound  Tool  Set  (#08) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Sound  Tool  Set  (#08) 
Note  Synthesizer  (#25) 


♦   Note.  The  Note  Sequencer  automatically  handles  the  startup  and  shutdown  of  the 
Sound  Tool  Set  (#8)  and  the  Note  Synthesizer  (#25). 
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List  Manager  (#28) 


Font  Manager  Tool  Locator  (#1) 

Memory  Manager  (#2) 
Miscellaneous  Tool  Set  (#3) 
QuickDraw  II  (#4) 
Integer  Math  (#11) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
List  Manager  (#28) 

LineEdit  (#20) 
Dialog  Manager  (#21) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  H  (#04) 
Event  Manager (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 

Audio  Compression  (ACE)  (#29)  Tool  Locator  (#01) 

Memory  Manager  (#02) 

MIDI  Tool  Set  (#32)  Tool  Locator  (#01) 

Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Sound  Tool  Set  (#8) 
Note  Synthesizer  (#25) 


For  chooseFont  only 

For  ChooseFont  only 
For  chooseFont  only 
For  ChooseFont  only 
For  FixFontMenu  only 
For  FixFontMenu  and 
ChooseFont  only 
For  ChooseFont  only 
For  ChooseFont  only 


For  time-stamping 
only 


♦   Note.  The  MIDI  Tool  Set  requires  the  Note  Synthesizer  in  order  to  support  the  MIDI 
clock  feature.  If  you  are  not  using  MIDI  clock,  the  Note  Synthesizer  is  not  required. 


Resource  Manager  (#30) 


Tool  Locator  (#01) 
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TextEdit  Tool  Set  (#34)  Tool  Locator  (#01)  Version  $0300 

Miscellaneous  Tool  Set  (#03)  Version  $0300 

QuickDraw  II  (#04)  Version  $0300 

QuickDraw  II  Auxiliary  (#18)  Version  $0206 

Event  Manager  (#06)  Version  $0300 

Window  Manager  (#14)  Version  $0300 

Control  Manager  (#16)  Version  $0300 

Menu  Manager  (#15)  Version  $0300 

Scrap  Manager  (#22)  Version  $0104 

Font  Manager  (#27)  Version  $0204 

Resource  Manager  (#30)  Version  $0100 
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New  Tool  Locator  calls 

The  call  setDef  auitTPT  has  been  added  to  the  Tool  Locator  to  facilitate  permanent 
tool  patches.  startupToois  and  shutDownToois  provide  automatic  services  for 
bringing  up  or  removing  tool  sets.  The  MessageByName  tool  call  provides  facilities  for 
your  application  to  use  the  message  center. 


MessageByName    $1701 

Creates  and  associates  a  name  with  a  new  message,  providing  a  convenient  and  extensible 
mechanism  for  creating,  tracking,  and  passing  messages  between  programs.  Your 
application  can  then  use  the  other  Message  Center  Tool  Locator  calls  to  manipulate  or 
delete  the  message. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


createltFlag 


recordPointer 


Long— Space  for  result 
Word— Boolean;  create  message? 
Long— Pointer  to  input  record 
<— SP 


Stack  after  call 


Previous  contents 


-  responseRecord  - 


Long— Response  record  from  call 
<— SP 
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Errors 


$0111 


messageNotFound 


$0112  messageOvfl 

$0113  nameTooLong 

Memory  Manager  errors 


No  message  found  with  specified 

name 

No  message  numbers  available 

Message  name  too  long 

Errors  from  NewHandie  returned 

unchanged 


extern  pascal  responseRecord 

MessageByName (createltFlag, 
recordPointer)  ; 


Boolean 
Pointer 


createltFlag; 
recordPointer; 


createltFlag  Determines  whether  to  create  a  message  containing  the  information 

from  the  input  record.  If  there  is  no  existing  message  with  the 
specified  name,  then  the  setting  of  createltFlag  governs  whether  to 
create  a  message.  If  there  is  already  a  message  with  the  specified 
name,  then  the  setting  of  createltFlag  determines  whether  to  replace 
that  existing  message  with  a  new  one  based  upon  the  input  record. 

recordPointer        Pointer  to  an  input  record,  which  defines  the  content  and 
characteristics  of  the  new  message: 


^  -         biookLen         -   Word— Length  of  record  (inducting  blockLen) 
$02 


namestring         :  n  Bytes— Identifier  string  for  the  message 


$02+n 


dataBioc*  :  m  Bytes— Optional  data  for  message 


blockLen  Contains  the  length,  in  bytes,  of  the  input  record.  Note  that  the 

value  for  this  field  includes  the  length  of  blockLen. 
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namestring        The  identifier  for  the  new  message.  This  is  a  standard  Pascal 
string  (length  byte  followed  by  ASCII  data),  with  a  maximum 
length  of  64  bytes  (not  including  the  length  byte).  In  order  to 
prevent  message  name  conflict,  this  name  string  should  contain 
the  the  manufacturer's  name,  followed  by  the  product  name 
and/or  code,  followed  by  a  unique  identifying  string.  You  may 
set  the  high-order  bits  of  each  byte;  note,  however,  that  the 
system  does  not  include  these  bits  in  name  comparisons. 

dataBiock  Application-defined  data  that  are  copied  into  a  created 

message.  Use  of  this  field  is  optional. 

responseRecord        Contains  the  response  information  from  the  call: 


$00 
$02 


—  createFlag 


messagelD 


Word— Boolean;  was  message  created? 
Word— ID  number  for  created  message 


createFlag        Indicates  whether  MessageByName  created  a  message.  Note 
that  if  you  set  createltFlag  to  TRUE  on  input  to 
MessageByName,  and  there  was  already  a  message  with  the 
specified  namestring  in  the  Message  Center,  then  this  flag  will 
be  FALSE,  and  messagelD  will  identify  the  message  into  which 
your  dataBiock  was  copied. 

messagelD  *        Message  ID  for  new  mesage,  if  MessageByName  created  one. 
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SetDefaultTPT     $1601 

Sets  the  default  Tool  Pointer  Table  (TPT)  to  the  current  TPT.  Used  to  permanendy  install  a 
tool  patch. 

A  Warning       An  application  should  not  make  this  call.A 
Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

C  extern  pascal  void  SetDefaultTPT () ; 
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ShutDownTools     $1901 

Shuts  down  the  tools  specified  in  the  input  start  stop  record. 

Your  program  must  pass  the  startstop  record  reference  that  was  returned  by 
StartUpTools. 

Parameters 

Stack  before  call 


Previous  contents 


startStopDesc 


-  startStopRecRef  - 


Stack  after  call 


Word— Defines  the  type  of  reference  stored  in  startStopRecRef 
Long— Reference  to  the  startstop  record 
<— SP 


Previous  contents 


Errors 
C 


startStopDesc 


StartStopRecRef 


None 


<— SP 


extern  pascal  void  ShutDownTools (startStopDesc, 
StartStopRecRef) ; 

Word      startStopDesc; 
Long      startStopRecRef; 

Defines  the  type  of  reference  stored  in  startStopRecRef. 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

Reference  to  the  updated  startstop  record  returned  by 
StartUpTools. 
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StartUpTools     $1801 

Starts  and  loads  the  tools  specified  in  the  input  startstop  record.  Upon  successful 
return  from  StartUpTools,  the  specified  tools  will  have  been  started  and  the  cursor  will 
be  represented  by  the  watch  image  (if  QuickDraw  II  Auxiliary  was  loaded).  Your  program 
should  change  the  cursor  image  before  accepting  user  input. 

Your  program  must  pass  the  startstop  record  reference  that  was  returned  by 
StartUpTools  to  the  shutDownToois  call  at  tool  shutdown  time. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


userlD 


startStopDesc 


-  StartStopRecRef  - 


Long— Space  for  result 

Word— Application  User  ID  for  system  calls 

Word— Defines  the  type  of  reference  stored  in  startStopRecRef 

Long— Reference  to  the  startstop  record 
<— SP 


Stack  after  call 


Previous  contents 


-startStopRecRefRet- 


Errors 


Long— Reference  to  resulting  startstop  record 
<— SP 


$0103          TLBadRecFlag 

startstop  record  invalid 

$0104          TLCantLoad 

A  tool  cannot  be  loaded-check 

input  startstop  record  for 

valid  tool  numbers,  and  versions 

and  for  correct  numToois  value 

System  Loader  errors 

Returned  unchanged 

Memory  Manager  errors 

Returned  unchanged 

GS/OS  errors 

Returned  unchanged 
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C  extern  pascal  long  StartUpTools (userlD, 

startStopDesc,  startStopRecRef ) ; 

Word      userlD,  startStopDesc; 
Long      startStopRecRef; 

startStopDesc         Defines  the  type  of  reference  stored  in  startStopRecRef. 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 

startStopRecRefRet  Reference  to  the  updated  startstop  record.  Your  application  must 
pass  this  record  to  the  shutDownToois  tool  call.  If  the  input  record 
reference  to  start UpToois  was  a  pointer,  then  this  reference  is  also 
a  pointer.  If  the  input  reference  was  either  a  handle  or  a  resource  ID, 
then  startupToois  returns  a  handle. 
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Chapter  52  Window  Manager  Update 


This  chapter  documents  new  features  of  the  Window  Manager.  The 
complete  reference  to  the  Window  Manager  is  in  Volume  2,  Chapter  25  of 
the  Apple  IIGS  Toolbox  Reference. 
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Error  corrections 

This  section  corrects  some  errors  in  the  Window  Manager  documentation  in  the  Apple  IIGS 
Toolbox  Reference. 

■  The  manual's  description  of  SetzoomRect  is  incorrect.  The  correct  description  is  as 
follows: 

Sets  the  f  zoomed  bit  of  the  window's  wFrame  record  to  0.  The  rectangle  passed  to 
SetzoomRect  then  becomes  the  window's  zoom  rectangle.  The  window's  size  and 
position  when  SetzoomRect  is  called  becomes  the  window's  unzoomed  size  and 
position,  regardless  of  what  the  unzoomed  characteristics  were  before  SetzoomRect 
was  called. 

■  Apple  IIGS  Toolbox  Reference  page  25-126,  third  line: 

If  wmTaskMask  bit  tmlnf  o  (bit  15)  *  1 

should  read: 

If  wmTaskMask  bit  tmlnf  o  (bit  15)  "  0 

■  When  used  with  a  window  that  does  not  have  scroll  bars,  the  call  windNewRes  calls  the 
window's  defProc  to  recompute  window  regions.  A  call  to  sizewindow  is  not 
necessary  under  these  circumstances. 
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New  features  in  the  Window  Manager 


This  section  explains  new  features  of  the  Window  Manager,  and  clarifies  points  that  were 
not  made  explicit  before. 

■  TaskMaster  now  brings  application  windows  to  the  front  after  dragging  is  complete. 
TaskMaster  previously  brought  windows  to  the  front  before  dragging. 

■  Using  the  SetOriginMask  call,  a  programmer  can  control  the  horizontal  scrolling 
characteristics  of  windows  that  TaskMaster  scrolls.  A  common  use  of 
SetOriginMask  is  to  ensure  that  the  window  origin  is  aligned  on  an  even  pixel,  so 
that  colors  do  not  change  if  the  display  mode  is  changed  between  320  and  640.  When 
using  the  call,  be  sure  that  the  horizontal  scroll  value  is  a  whole  multiple  of  the  mask 
value.  Otherwise,  strange  behavior  can  occur.  As  an  extreme  example,  consider  an 
origin  value  of  32  and  a  scroll  amount  of  1 .  Using  the  right  scroll  arrow  will  not  scroll  the 
window  at  all,  and  using  the  left  one  will  scroll  it  by  a  value  of  32.  The  new  control  value 
for  the  scrolling  is  calculated  by  adding  or  subtracting  the  scroll  value  and  the  current 
value  and  applying  the  mask.  In  this  case  adding  1  and  masking  results  in  the  original 
value.  Subtracting  1  and  masking  results  in  a  new  value  that  is  32  less  than  the  old  value. 

■  Standard  windows  can  now  draw  their  tides  in  16  colors  regardless  of  mode. 

■  The  grid  parameter  of  the  call  Dragwindow  has  been  renamed  dragFlag.  Bits  0 
through  7  specify  the  grid  value.  Bits  8  through  14  are  reserved  bits;  they  must  be  set  to 
0.  Bit  15  is  a  selection  flag;  if  its  value  is  1,  then  the  window  will  be  brought  to  the  top 
after  dragging. 

■  It  is  no  longer  possible  to  specify  grid  values  of  256  or  512. 

■  The  Window  Manager  now  uses  the  same  default  desktop  drawing  scheme  as  the  . 
Finder.  When  the  Window  Manager  starts  up,  it  looks  for  a  DeskMessage  in  the 
message  center.  This  DeskMessage  is  formatted  as  follows: 


$00 

$04 
$06 
$08 


Reserved 


—  messType 


—  drawType 


Long— Used  by  message  center 


Word— Message  type:  must  be  set  to  $0002 


-   Word— Indicates  content  of  drawData 


drawoata  :  Array— Data  for  desktop;  type  specified  in  drawType 

i 
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drawType  Indicates  the  type  of  data  stored  at  drawData: 

0  drawData  contains  pattern  information 

1  drawData  contains  picture  information 

drawData  Contains  the  pattern  or  picture  data  for  the  desktop  image.  If 

drawType  is  set  to  0,  then  drawData  contains  32  bytes  of 
pattern  data.  The  pattern  defines  (A  pixels  arranged  in  an  8-by-8 
array.  In  320  mode  4  bits  are  needed  for  each  pixel;  in  640  mode, 
the  system  requires  2  bits  per  pixel.  The  system  uses  this  pattern 
to  seed  the  desktop  image. 

If  drawType  is  setto  1,  then  drawData  contains  32,000  bytes 
of  picture  data;  the  system  copies  this  data  direcdy  to  screen 
memory.  See  Chapter  16,  "QuickDraw  II,"  in  the  Toolbox 
Reference  for  details  on  pattern  or  picture  images. 

By  loading  a  DeskMessage  into  the  message  center,  your  program  can  set  a  custom 
desktop  image. 

Window  Manager  now  supports  a  new  entry  point,  TaskMasterDA,  that  allows  desk 
accessories  to  use  TaskMaster.  Previously,  desk  accessories  could  not  rely  on 
TaskMaster,  because  they  had  to  work  with  applications  that  do  not  use  TaskMaster. 
Desk  accessories  obtain  the  data  for  their  task  record  from  the  Desk  Manager. 
TaskMaster  processes  task  records  for  desk  accessories  in  the  same  way  that  it 
processes  application  task  records. 

The  SizeWindow  and  ResizeWindow  tool  calls  now  invoke  the  NotifyCtls 
Control  Manager  tool  call  whenever  the  user  changes  the  window  size.  This  allows 
applications  to  show  a  control  in  a  constant  position  with  respect  to  the  lower  or  right 
border  of  a  window.  For  example,  now  the  growcontroi  control  definition 
procedure  can  automatically  move  controls  in  response  to  a  user  dragging  the  size  box. 
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Alert  windows 

The  new  Alert  window  call  (described  in  "New  Window  Manager  calls,"  later  in  this 
chapter)  can  be  used  to  create  alert  windows  for  presenting  the  user  with  important 
messages.  An  alert  window  is  similar  to  a  modal  dialog  box.  It  requires  that  the  user  click  a 
button  in  the  window  before  doing  anything  else,  and  so  provides  a  useful  way  to 
communicate  vital  messages  such  as  warnings  or  error  reports.  The  call  does  all  the  work  of 
creating  and  displaying  the  window  and  contents  for  the  alert,  and  returns  the  ID  of  the 
button  that  the  user  chooses. 

Alertwindow  accepts  a  reference  to  a  string  that  contains  its  message,  and  a  reference 
to  an  array  of  substitution  strings.  The  substitution  strings  can  be  any  of  seven  standard 
strings  (such  as  "OK,"  "Continue,"  and  so  on)  or  can  be  specified  by  the  application  and 
stored  in  the  buffer  to  which  the  substitution-string  pointer  refers.  The  format  of  the 
Alertwindow  input  string  is 


$00 

size 

Block 

$xx 

ioonSpec 

Block 

$xx 

separator 

Byte 

$xx 

messageText 

Character  array 

$xx 

sep 

Byte 

$xx 

buttonStrings 

:  Character  array 

$xx 

terminator 

Byte 
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Size 


A  variable-length  block  that  specifies  the  size  of  the  alert  window  to 
be  displayed.  Valid  ASCII  values  for  the  first  byte  lie  in  the  range  from 
0  through  9  and  have  the  following  meanings: 

0  Custom  size  and  position,  specified  by  rectangle 
definition  (as  shown  below) 

1  30-character  display  window 

2  60-character  display  window 

3  110-character  display  window 

4  175-character  display  window 

5  110-character  display  window 

6  150-character  display  window 

7  200-character  display  window 

8  250-character  display  window 

9  300-character  display  window 

If  the  value  of  the  first  byte  of  size  is  not  0,  then  the  block  consists 
only  of  that  byte.  If  size  is  set  to  0,  then  you  must  specify  the  custom 
rectangle  immediately  after  the  size  field: 


vl 


hi 


v2 


h2 


Word— y  cooridnate  of  upper-left  corner 
Word— x  cooridnate  of  upper-left  corner 
Word— y  cooridnate  of  lower-right  corner 
Word— x  cooridnate  of  lower-right  corner 


Since  Alertwindow  provides  a  limited  number  of  standard  sizes,  it 
is  possible  to  create  alerts  that  display  properly  whether  the  Apple 
HGS  is  in  320  or  640  mode.  It  is  necessary,  however,  to  design  the  text 
and  buttons  carefully  in  order  to  make  this  work. 

Table  52-1  shows  the  dimensions  of  the  standard  alert  windows.  This 
table  gives  only  an  approximate  idea  of  the  size  of  each  window. 
Application  code  should  not  rely  on  the  exact  widths,  heights,  or 
position  of  standard  windows. 
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Table  52-1       Standard  alert  window  sizes 


size  value 


Height  320 


Width  320 


Height  640 


Width  640 


1 

46 

152 

46 

200 

2 

62 

176 

54 

228 

3 

62 

252 

62 

300 

4 

90 

252 

72 

352 

5 

54 

252 

46 

400 

6 

62 

300 

54 

452 

7 

80 

300 

61 

500 

8 

108 

300 

11 

552 

9 

134 

300 

80 

600 

iconSpec 


A  variable-length  block  that  specifies  the  type  of  icon  to  be  displayed 
in  the  alert  window.  Valid  ASCII  values  for  the  first  byte  lie  in  the  range 
from  o  through  9  and  have  the  following  meanings: 


0 

No  icon 

1 

Custom  icon;  followed  by  an  icon  specification,  as 
shown  below 

2 

Stop  icon 

3 

Note  icon 

4 

Caution  icon 

5 

Disk  icon 

6 

7-9 

Disk  swap  icon 
Reserved 

If  the  first  byte  of  iconSpec  has  a  value  other  than  l,  then  the  field 
consists  only  of  that  byte.  If  the  first  byte  is  set  to  l,  then  it  must  be 
followed  by  an  icon  specification: 


imageptr         -   Long— Pointer  to  image  data 


—    imageWidth 


Word— Width,  in  bytes,  of  the  image  data 
-       imageHeight       -|  Word— Height  in  scan  lines,  of  the  image  data 
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separator 


messageText 


sep 
buttonStrings 


terminator 


Specifies  a  character  that  will  divide  sub-strings  in  the  remainder  of 
the  Alertwindow  input  string.  The  separator  field  can  contain  any 
character,  but  the  character  cannot  appear  in  the  message  text  or 
button  strings.  The  separator  character  divides  the  message  from  the 
first  button  string  and  the  button  strings  from  each  other.  For 
purposes  of  standardization,  the  slash  (/)  character  is  recommended, 
unless  you  will  be  substituting  pathnames. 

Do  not  include  a  separator  character  in  any  substitution  strings.  The 
Window  Manager  performs  substitutions  before  scanning  the  alert 
string  for  separators.  For  example,  if  the  separator  character  is  a  slash 
and  a  pathname  containing  several  slashes  is  substituted  for  the  string, 
the  resulting  alert  window  will  contain  several  more  buttons  than  you 
intended. 

Specifies  the  message  to  be  displayed  in  the  alert  window.  Any 
characters  allowed  by  le  Text  box  2  are  allowed  in  the  message  text. 
See  "Special  Characters"  later  in  this  chapter  for  additional 
characteristics  of  Alertwindow  message  text.  The  total  size  of 
message  text,  after  substitution  of  strings,  is  limited  to  1000 
characters. 

A  separator  character. 

Specifies  titles  for  up  to  three  buttons  to  be  displayed  in  the  alert 
window.  If  there  is  more  than  one  title,  then  the  titles  must  be 
separated  from  one  another  by  a  separator  character.  These  buttons 
will  be  evenly  spaced  and  centered  at  the  bottom  of  the  alert  window. 
The  width  of  each  button  is  the  same  and  is  set  by  the  widest  button 
title.  The  maximum  length  of  button  text  after  substitution  of  strings 
is  80  characters. 

Marks  the  end  of  the  alert  string.  Must  be  set  to  0  ($00). 
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Special  characters 

The  following  special  characters  can  be  embedded  in  the  message  text  and  button 
strings  of  an  Alertwindow  input  string.  If  a  special  character  is  to  appear  in  the  text  of  a 
button  or  message,  you  must  enter  it  twice  in  the  string.  For  example,  if  you  want  "*"  to 
appear  in  an  alert  message,  you  must  enter  it  in  the  message  string  as  "~/v". 

A  caret  (A)  designates  the  default  button.  The  default  button  is  the 
button  selected  if  the  user  presses  the  Return  key  on  the  keyboard.  This 
button  will  also  appear  oudined  in  bold  on  the  screen.  Only  one  button 
can  be  the  default  button.  After  the  caret,  the  button  tide  must  follow, 
as  for  any  other  button.  Other  special  characters  may  also  appear  after 
the  caret.  A  single  caret  in  the  body  of  message  text  has  no  effect  and  is 
deleted  from  the  message. 

#  Substitute  standard  string.  The  number  sign  (#)  must  be  followed  by  a 
decimal  number.  Numbers  0  through  6  can  be  used.  Numbers  7  through  9 
are  reserved  and  should  not  be  used.  The  standard  substitution  strings  are 

#0  OK 

#i  Cancel 

#2  Yes 

#3  No 

#4  Try  Again 

#5  Quit 

#6  Continue 

*  Substitute  given  string.  The  asterisk  (*)  character  followed  by  an  ASCII 
decimal  number  from  '0'  through  '9'  denotes  a  substitution  string  to  be 
inserted  at  that  point.  The  asterisk  and  the  following  number  will  be 
replaced  by  the  corresponding  string  in  the  specified  substitution  array. 
A  pointer  to  the  substitution  array  is  passed  as  a  parameter  to  the 
Alertwindow  call.  The  substitution  array  is  defined  as  an  array  of 
pointers.  Table  52-2  shows  the  format  of  a  substitution  string  array. 
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Table  52-2        Substitution  string  array 


LONG[0] 
L0NGI1] 
LONG[2] 
LONGB] 
LONG[4] 
LONG[5] 
LONGI6] 
LONGI7] 
LONGI8] 
LONG[9] 


Pointer  to 
Pointer  to 
Pointer  to 
Pointer  to 
Pointer  to 
Pointer  to 
Pointer  to 
Pointer  to 
Pointer  to 
Pointer  to 


string  that  will 
string  that  will 
string  that  will 
string  that  will 
string  that  will 
string  that  will 
string  that  will 
string  that  will 
string  that  will 
string  that  will 


substitute 
substitute 
substitute 
substitute 
substitute 
substitute 
substitute 
substitute 
substitute 
substitute 


for  *o 
for  *i 
for  *2 
for  *3 
for  *4 
for*  5 
for  *6 
for  *7 
for  *8 
for  *9 


Substitution  strings  can  be  C  strings  or  Pascal  strings,  or  may  be  terminated  by  a  carriage 
return.  A  parameter  to  the  Alertwindow  tool  call  allows  you  to  specify  the  type  of 
strings  in  the  substitution  array. 

Alert  window  example 

Following  are  some  examples  of  alert  strings  that  can  be  passed  to  Alertwindow  in 
65816  Assembly  language  syntax. 

A  simple  alert  string: 


dc   c'13/Text  of  Message/Button  l'^il'O' 


by^WwideA \Icon      \Message         Button  title. 


^ 

Te»t  of  Message 


Button  1 


Zero  terminates  alert. 
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A  more  complex  alert  string: 

dc   c'51/This  is  the  *0  of  *3  alert  *2*1  and  standard' 

dc   c'text  called  "#4"  /* 

dc   c '*#(),  Really/*4/Yo! ',11' 0' 


© 

This  is  the  message  tent  of  an  alert  window  and  standard 
tent  called  "Try  Again." 

[OK,  Really  1 

Door  #2                                   Vo!        ] 

Where  the  substitution  array 

dc 
subO  dc 
subl  dc 
sub2  dc 
sub3  dc 
sub4  dc 


14 ' subO, subl,sub2,sub3, sub4 ' 

c' message  text1, 11' 0' 

c ' dow • , il • 0 ' 

c'win'jil'lS' 

c'an^il'O" 

c'Door  #2',il,0I 
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TaskMaster  result  codes 


Table  52-3  lists  all  the  possible  TaskMaster  result  codes. 


Table  52-3       TaskMaster  result  codes 


Name 

Value 

Description 

Null 

$0000 

Successful 

mouseDownEvt 

$0001 

Event  Code  - 

mouseUpEvt 

$0002 

Event  Code  - 

keyDownEvt 

$0003 

Event  Code  - 

autoKeyEvt 

$0005 

Event  Code  - 

updateEvt 

$0006 

Event  Code  - 

activateEvt 

$0008 

Event  Code  - 

switchEvt 

$0009 

Event  Code  - 

deskAccEvt 

$000A 

Event  Code  - 

drive rEvt 

$000B 

Event  Code  - 

applEvt 

$000C 

Event  Code  - 

app2Evt 

$000D 

Event  Code  - 

app3Evt 

$000E 

Event  Code  - 

app4Evt 

$000F 

Event  Code  - 

wNoHit 

$0000 

Alias  for  no  event 

inNull 

$0000 

Alias  for  no  event 

inKey 

$0003 

Alias  for  keystroke 

inButtDwn 

$0001 

Alias  for  button  down 

inUpdate 

$0006 

Alias  for  update  event 

wlnDesk 

$0010 

On  Desktop 

wlnMenuBar 

$0011 

On  System  Menu  Bar 

wClickCalled 

$0012 

Systemciick  called  (returned  only  as  action) 

wlnContent 

$0013 

In  content  region 

wlnDrag 

$0014 

In  drag  region 

wlnGrow 

$0015 

In  grow  region,  active  window  only 

wlnGoAway 

$0016 

In  go-away  region,  active  window  only 
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wlnZoom 

$0017 

wlnlnfo 

$0018 

wlnSpecial 

$0019 

wlnDeskltem 

$001A 

wlnFrame 

$001B 

wlnactMenu 

$001C 

wClosedNDA 

$001D 

wCalledSysEdit 

$001E 

wTrackZoom 

$001F 

wHitFrame 

$0020 

wlnControl 

$0021 

wlnControlMenu     $0022 


In  zoom  region,  active  window  only 

In  information  bar 

Item  ID  selected  was  250-255 

Item  ID  selected  was  1-249 

In  frame,  but  not  on  anything  else 

Inactive  menu  item  selected 

Desk  accessory  closed  (returned  only  as  action) 

SystemEdit  called  (returned  only  as  action) 

Zoom  box  clicked,  but  not  selected  (action  only) 

Button  down  on  frame,  made  active  (action  only) 

Button  or  keystroke  in  control  (can  be  returned  as 

event  code  and  as  action) 

Control  handled  menu  item 


wmsyswindow        $8000        High  bit  set  for  system  windows 
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Window  Manager  data  structures 

This  section  discusses  the  format  and  content  of  changed  Window  Manager  data 
structures. 

Window  record 

The  window  record  data  structure  has  been  redefined.  The  new  definition  is  illustrated  in 
Figure  52-1. 
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Figure  52-1      Window  record  definition 


$00 
$04 

$AE 

$B2 

$B6 

$BA 

$BE 

$C2 

$C6 

$CA 

$CE 
$D2 

$D4 


—     wDefProc 


—     wStructRgn 


wRefCon 


wContDraw 


wReserved     — 


wContRgn 


—     wUpdateRgn 


wCtls 


Long— Pointer  to  next  window;  NIL  at  end  of  list 
:  Array— Window's  grafPort  (170  bytes) 
Long— Pointer  to  control  definition  procedure 

Long— Reserved  for  application  use 

Long— Pointer  to  routine  to  draw  window  contents 

Long— Reserved  for  use  by  Window  Manager;  do  not  use 

Long— Handle  to  window's  structure  region 

Long— Handle  to  window's  content  region 

Long— Handle  to  window's  update  region 

Long— Handle  to  first  control  in  window's  control  chain 


wFramectis        -   Long— Handle  to  first  control  in  window's  frame 


wFrame  -   Word— Flags  for  window 


wcustom  :  Array— Additional  data  for  window  definition  procedure 
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wRe served 


wFrame 


A  new  data  field  reserved  by  Apple  Computer,  Inc.  for  future 
expansion. 

A  bit  flag,  containing  flags  specifying  the  window  frame.  All  of  the  bits 
in  this  flag  are  described  in  Chapter  25,  "Window  Manager,"  in 
Volume  2  of  the  Toolbox  Reference.  Some  of  these  bits  may  be  used  by 
window  definition  procedures.  The  following  table  lists  the  bits  that 
may  be  used  by  window  defProcs. 


fTitle 

bit  15 

fClose 

bit  14 

f Alert 

bit  13 

fRScroll 

bit  12 

fBScroll 

bit  11 

fGrow 

bit  10 

fFlex 

bit  9 

fZoom 

bit  8 

fMove 

bit  7 

flnfo 

bit  4 

fZoomed 

bitl 
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Task  record 

Figure  52-2  defines  the  new  format  for  the  task  record.  This  new  record  layout  includes 
several  new  fields,  each  of  which  is  set  by  Taskmaster  every  time  your  program  calls 
TaskMaster.  For  information  on  the  old  fields,  see  Chapter  25,  "Window  Manager,"  in  the 
Toolbox  Reference. 

TaskMaster  will  still  accept  old-format  task  records;  however,  if  your  program  uses  any  of 
the  new  TaskMaster  features  (see  wmTaskMask),  it  must  use  the  new  record  layout. 


Chapter  52    Window  Manager  Update     52-17 


Apple  I1GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Figure  52-2      Task  Record  definition 

Word— Same  as  before 
Long— Same  as  before 

-|  Long— Same  as  before 

Long— Same  as  before 
Word— Same  as  before 
Long— Same  as  before 


$00 

wmWhat 

- 

$02 

— 

wmMessage 

- 

— 

$06 

_ 

wmWhen 

- 

— 

$0A 

_ 

wmWhere 

- 

— 

$0E 

wmModifiers 

- 

$10 

— 

wmTaskData 

- 

— 

$14 

_ 

wmTaskMask 

- 

— 

$18 

— 

- 

wmLastClickTick 

- 

— 

$1C 

wmClickCount 

- 

$1E 

— 

wmTaskData2 

- 

- 

$22 

— 

wmTaskData3 

- 

- 

$26 

_ 

wmTaskData4 

- 

— 

$2A 

-   Long— Flags  controlling  TaskMaster  function 


-   Long— System  tick  value  at  last  mouse  click 


-  Word— Type  of  last  click  (single  double,  triple) 


-   Long— Additional  TaskMaster  return  data 


Long— Additional  TaskMaster  return  data 


Long— Additional  TaskMaster  return  data 


:       wmLastciickPt       '■  Point— Location  of  last  mouse  click 
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taskMask 


Flag  controlling  TaskMaster  function: 


Reserved  bits  21-31 

tmldleEvents  bit  20 


tmMultiClick  bit  19 


tmControlMenu  bit  18 


tmControlKey  bit  17 


tmContentControls 


bit  16 


tmlnfo 


tmlnactive 


tmCRedraw 


tmSpecial 


bit  15 


bit  14 


bit  13 


bit  12 


Must  be  set  to  0 

Controls  whether  TaskMaster  sends  idle  events  to  the 

target  control  in  the  active  window: 

1  -  Send  idle  events 

0  -  Do  not  send  idle  events 

Controls  whether  TaskMaster  returns  multiclick 
information  in  the  Task  Record: 

1  -  Return  multiclick  information 

0  -Do  not  return  multiclick  information 

Controls  whether  TaskMaster  passes  menu  events  to 
controls  in  the  active  window: 

1  -  Pass  menu  events 

0  -  Do  not  pass  menu  events 

Controls  whether  TaskMaster  passes  key  events  to 
controls  in  the  active  window: 

1  -  Pass  key  events 

0  -  Do  not  pass  key  events 

Controls  whether  TaskMaster  calls  Findcontroi 
and  TrackControi  when  Findwindow  returns 
winContent  and  the  window  is  already  selected: 

1  -  Track  the  control 

0  -  Do  not  track  the  control 

Controls  whether  TaskMaster  activates  the  window 
when  the  user  clicks  in  the  info  bar: 

1  -  Do  not  activate  the  window 

0  -  Activate  the  window 

Controls  whether  TaskMaster  returns  winactMenu 
when  the  user  selects  an  inactive  menu  item: 

1  -  Return  winactMenu 

0  -  Never  return  winactMenu 

Controls  whether  TaskMaster  redraws  controls 
whenever  an  activate  event  occurs: 

1  -  Redraw  controls 

0  -  Do  not  redraw  controls 

Controls  whether  TaskMaster  handles  special  menu 
items  (those  with  IDs  <  256): 

1  -  Handle  special  menu  items 

0  -  Do  not  handle  special  menu  items 
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tmScroll 


tmGrow 


tmZoom 


tmClose 


tmContent 


tmDragW 


tmSysClick 


tmOpenNDA 


tmMenuSel 


tmFindW 


bit  11         Controls  whether  TaskMaster  enables  scrolling  and 
activates  inactive  windows  when  the  user  clicks  on 
the  scroll  bar: 
1  -  Enable  scrolling 

0  -  Do  not  enable  scrolling 

bit  10         Controls  whether  TaskMaster  calls  Growwindow 
when  the  user  drags  the  size  box: 

1  -  Call  GrowWindow 

0  -  Do  not  call  GrowWindow 

bit  9  Controls  whether  TaskMaster  calls  Trackzoom  when 

the  user  clicks  in  the  zoom  box: 

1  -  Call  TrackZoom 

0  -  Do  not  call  TrackZoom 

bit  8  Controls  whether  TaskMaster  calls  TrackGoAway 

when  the  user  clicks  in  the  close  box: 

1  -  Call  TrackGoAway 

0  -  Do  not  call  TrackGoAway 

bit  7  Controls  whether  TaskMaster  activates  the  window 

when  the  user  clicks  in  the  content  region: 

1  -  Activate  window 

0  -  Do  not  activate  window 

bit  6  Controls  whether  TaskMaster  calls  Dragwindow 

when  the  user  drags  in  the  drag  region: 

1  -  Call  DragWindow 

0  -  Do  not  call  DragWindow 

bit  5  Controls  whether  TaskMaster  calls  Systemciick 

when  the  user  clicks  in  the  system  window: 

1  -  Call  SystemClick 

0  -  Do  not  call  SystemClick 

bit  4  Controls  whether  TaskMaster  calls  openNDA  when  the 

user  selects  a  desk  accessory: 

1  -  Call  OpenNDA 

0  -  Do  not  call  OpenNDA 

bit  3  Controls  whether  TaskMaster  calls  MenuSeiect 

when  the  user  clicks  in  the  menu  bar: 

1  -Call  MenuSeiect 

0  -  Do  not  call  MenuSeiect 

bit  2  Controls  whether  TaskMaster  calls  Findwindow  for 

mouse-down  events: 

1  -  Call  Findwindow 

0  -  Do  not  call  Findwindow 
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tmupdate  bit  1  Controls  whether  TaskMaster  handles  update  events: 

1  -  Handle  update  events 

0  -  Do  not  handle  update  events 
tmMenuKey  bit  0  Controls  whether  TaskMaster  calls  MenuKey  to 

handle  menu  key  equivalents: 

1- Call  MenuKey 

0  -  Do  not  call  Menukey 
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New  Window  Manager  calls 

The  following  tool  calls  have  been  added  to  the  Window  Manager  since  publication  of  the 
first  two  volumes  of  the  Apple  IIGS  Toolbox  Reference. 


AlertWindow     $590E 

Creates  an  alert  window  that  displays  a  message  referred  to  by  alertStrRef.  The  message 
can  be  either  a  C  or  a  Pascal  string,  as  specified  by  alertFlags.  The  subStrPtr  parameter 
points  to  an  array  of  substitution  strings  for  use  with  substitution  characters.  For  more 
detailed  information,  see  "Alert  Windows"  earlier  in  this  chapter. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


alertFlags 


subStrPtr 


-      alertStrRef     - 


Word— Space  for  result 
Word— Flag  word  for  call 

Long— Pointer  to  substitution  array 

Long— Reference  to  alert  stnng-alertFlags  indicates  type 

<— SP 


Stack  after  call 


Previous  contents 


Result 


Errors 


None 


Word— Button  number  selected 
<— SP 
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C  extern  pascal  Word  AlertWindow(alertFlags, 

subStrPtr,  alertStrRef) ; 

Word      alertFlags; 
Pointer   subStrPtr; 
Long      alertStrRef; 

alertFlags  Contains  flags  that  indicate  the  type  of  strings  referenced  by 

alertStrRef,  as  well  as  the  type  of  reference  contained  that  field: 

Reserved  bits  3-15     Must  be  set  to  0 

ref  erenceType        bits  1-2      Indicate  the  type  of  reference  stored  in  alertStrRef. 

00  -  alertStrRef  is  a  pointer 

01  -  alertStrRef  is  a  handle 

10  -  alertStrRef  'is  a  resource  ID 
stringType  bit  0  Indicates  type  of  string  referred  to  by  alertStrRef 

0  -  C  string  (null-terminated) 

1  -  Pascal  string 
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CompileText     $600E 

Combines  source  text  provided  by  your  program  with  either  custom  or  standard  strings  to 
compile  a  result  text  string.  For  successful  calls,  this  call  allocates  and  correctly  sizes  a 
handle  to  the  result  text  string.  That  result  string  is  a  simple  character  array.  Your  program 
must  extract  length  information  for  the  string  from  the  handle.  Note  that  your  program 
must  dispose  of  this  handle. 

Control  sequences  in  the  source  text  direct  the  system  to  embed  either  custom  or 
standard  strings  into  the  result  text  string.  These  control  sequences  consist  of  two  ASCII 
characters:  a  flag  character  followed  by  a  digit.  The  flag  character  indicates  whether  the 
desired  substitution  string  is  custom  or  standard. 

For  standard  strings,  the  flag  character  is  #.  The  digit  following  the  flag  character  selects 
one  of  the  following  strings: 


#0 

OK 

#1 

Cancel 

#2 

Yes 

#3 

No 

#4 

Try  Again 

#5 

Quit 

#6 

Continue 

For  custom  strings,  the  flag  character  is  *.  CompileText  obtains  custom  strings  from  a 
substitution  array  built  by  your  program  and  provided  to  the  system  in  the  parameters  for 
this  call.  The  character  following  the  flag  character  specifies  which  string  to  extract.  Valid 
values  for  this  character  lie  in  the  range  o  through  9.  Thus,  a  control  sequence  of  *  o  would 
access  the  first  string  in  your  custom  substitution  array. 

In  order  to  include  either  of  the  flag  characters  as  text  in  your  compiled  text,  follow  the 
flag  character  with  a  second  flag  character  (for  example,  **  results  in  *  in  the  compiled 
text  string). 
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Parameters 

Stack  before  call 


Previous  contents 


Space 


subType 


-    subStringsPtr   - 


-    srcStringPtr    - 


srcSize 


Stack  after  call 


Long— Space  for  result 

Word— Type  of  custom  substitution  strings 

Long— Pointer  to  substitution  array 

Long— Pointer  to  source  string 

Word— Length  of  source  string  pointed  to  by  srcStringPtr 

<— SP 


Previous  contents 


-    stringHandle    - 


Errors 
C 


subType 

0 
1 


Long— Handle  to  result  string 

<— SP 

$0E04        compiieTooLarge  Compiled  text  is  larger  than  64k 

extern  pascal  Handle  CompileText (subType, 

subStringsPtr,  srcStringPtr,  srcSize) ; 

Word      subType,  srcSize; 

Pointer   subStringsPtr,  srcStringPtr; 

Indicates  the  type  of  strings  stored  in  the  substitution  array  pointed 
to  by  subStringsPtr. 

Array  contains  C  strings 
Array  contains  Pascal  strings 

Note  that  this  field  is  ignored  if  your  program  does  not  use  any 
custom  substitution  strings. 
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subStringsPtr         Contains  a  pointer  to  your  custom  text  substitution  array.  This  array 
contains  from  1  to  10  long  pointers  to  either  C  or  Pascal  strings  (use 
subType  to  indicate  which  type  of  string  you  have  used).  Embedded 
control  sequences  in  your  source  text  direct  the  system  to  extract  a 
specific  string  from  this  array.  Note  that  the  system  does  not  verify 
string  specifications  against  the  size  of  this  array;  be  careful  to  define 
the  correct  number  of  string  pointers  in  this  array. 

Note  that  this  field  is  ignored  if  your  program  does  not  use  any 
custom  substitution  strings. 
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DrawInfoBar     $550E 

Redraws  the  info  bar  of  the  window  specified  by  grafPortPtr.  The  method  used  to  redraw 
the  info  bar's  interior  is  the  routine  specified  by  the  wlnfoDeJProc  field  of  the 
paramList  passed  to  Newwindow  when  the  window  is  created.  The  Window  Manager 
will  automatically  clip  info  bar  drawing  to  the  dimensions  of  the  info  bar,  and  to  the 
visible  region  of  the  window. 


Parameters 

Stack  before  call 

Previous  contents 

-     grafPortPtr    - 

Long— Pointer  to  GrafPort  for  window 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C 

exte 

rn  p 

ascal  void  DrawInfoBar (grafPor 

Pointer        grafPortPtr; 
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EndFrameDrawing     $5B0E 

Restores  Window  Manager  variables  after  a  call  to  startFrameDrawing. 
Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  None 

C  extern  pascal  void  EndFrameDrawing () ; 
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ErrorWindow    $620E 

Creates  a  dialog  box  displaying  an  error  message  for  a  specified  error  code.  GS/OS  error 
codes  are  listed  along  with  standard  message  text  in  "Error  messages"  later  in  this  chapter. 

Each  error  message  is  in  alert  string  format  and  may  require  a  substitution  string  (see  "Alert 
windows"  earlier  in  this  chapter  for  message  format  and  text  substitution  information). 
The  system  retrieves  the  error  messages  from  a  resource  file  of  type  $8020.  The  resource  ID 
for  each  message  is  formed  as  follows: 


high-order  word 
low-order  word 


$07FF 
error  number 


The  default  error  messages  are  stored  in  the  system  resources  file.You  may  assert  custom 
error  message  text  by  defining  and  opening  another  resource  file  containing  type  $8020 
resources  with  appropriate  resource  IDs  assigned  to  each  error  message.  Make  sure  that 
your  resource  file  precedes  the  system  resource  file  in  the  Resource  Manager's  search 
sequence.  A  custom  error  message  resource  file  need  not  define  substitute  messages  for 
all  possible  GS/OS  errors;  if  the  Resource  Manager  does  not  find  a  message  in  your  file,  it 
will  continue  through  the  standard  resource  search  sequence. 

If  ErrorWindow  receives  an  undefined  error  code,  it  displays  a  dialog  box  with  the 
"Unknown  Error"  message  ($72). 

Parameters 

Stack  before  call 


Previous  contents 


Space 


subType 


-    subStringPtr 


errNutn 


Word— Space  for  result 

Word— Type  of  custom  substitution  string 

Long— Pointer  to  substitution  string 
Word— GS/OS  error  number 
<— SP 


Stack  after  call 


Previous  contents 


buttonNumber 


Word— Number  of  button  pressed  by  the  user 
<— SP 
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Errors 
C 


Resource  Manager  errors 


subType 

0 

1 


returned  unchanged 


extern  pascal  Word  ErrorWindow (subType, 
subStringPtr,  errNum) ; 

Word      subType,  errNum; 
Pointer   subStringPtr; 

Indicates  the  type  of  string  pointed  to  by  subStringPtr. 


C  string 
Pascal  string 

Note  that  this  field  is  ignored  if  the  specified  error  message  does  not 
use  any  substitution  strings. 

subStringPtr  Contains  a  pointer  to  your  custom  text  substitution  string. 

Note  that  this  field  is  ignored  if  the  specified  error  message  does  not 
use  any  substitution  strings. 
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GetWindowMgrGlobals     $580E 

Returns  a  pointer  to  the  Window  Manager  global  data  area. 


▲  Warning       An  application  should  never  make  this  call 


Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


-  globalDataPtr 


Errors 
C 


None 


Long— Pointer  to  the  global  data  area 
<— SP 


extern  pascal  Pointer  GetWindowMgrGlobals () ; 
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NewWindow2     $6lOE 

Performs  the  same  function  as  Newwindow,  but  allows  you  to  specify  the  input  window 

template  as  a  resource  (type  rWindParaml  or  rWindParam2).  See 

Appendix  E,  "Resource  Types,"  later  in  this  book  for  complete  descriptions  of  all  resource 

types. 


♦  Note.  If  you  have  specified  the  window  template  as  a  resource,  then  the  references 
within  that  template  to  title,  color  table,  and  control  list  must  also  be  resources  (or 
NIL). 


♦  Note.  In  order  to  create  an  InfoBar  with  Newwindow2  using  a  window  template 
defined  as  a  resource,  you  must  specify  a  NIL  inf  oDraw  procedure  in  the  input 
template  and  create  an  invisible  window.  After  issuing  the  Newwindow2  call,  set  the 
inf  oDraw  routine  by  calling  setmf  oDraw,  then  make  the  window  visible  with  the 
ShowWindow  tool  call. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


titlePtr 


refCon 


-  contentDrawPtr  ■ 


-     defProcPtr     - 


paramTableDesc 


-  paramTableRef 


resourceType 


Long— Space  for  result 

Long— Pointer  to  replacement  title 

Long— RefCon  to  replace  value  in  template 

Long— Pointer  to  replacement  content  draw  Routine 

Long— Pointer  to  replacement  window  definition  procedure 

Word— Indicates  type  of  reference  in  paramTableRef 

Long— Reference  to  window  template 

Word— Resource  type  of  template  referred  to  by  paramTableRef 

<— SP 
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Stack  after  call 


Previous  contents 


-     grajPortPtr    - 


Long— Pointer  to  window  GrafPort;  NIL  if  unsuccessful 
<— SP 

Errors  Resource  Manager  errors  returned  unchanged 

Memory  Manager  errors  returned  unchanged 

Window  Manager  errors  returned  unchanged  from 

NewWindow 
Control  Manager  errors  returned  unchanged  from 

NewControl2 

C  extern  pascal  Pointer  NewWindow2 (titlePtr,  refCon, 

contentDrawPtr,  defProcPtr, 
paramTableDesc,  paramTableRef , 
resourceType) ; 

Word      paramTableDesc,  resourceType; 
Pointer   titlePtr,  contentDrawPtr,  defProcPtr; 
Long      refCon,  paramTableRef; 

titlePtr,  refCon,  contentDrawPtr,  defProcPtr 

Newwindow2  will  replace  the  values  supplied  in  the  template  referred 
to  by  paramTableRef  m\h  the  contents  from  these  fields,  allowing  you 
to  use  a  standard  template  and  tailor  it  to  create  different  windows. 
To  prevent  Newwindow2  from  replacing  the  template  values,  supply 
NIL  pointers  in  titlePtr,  contentDrawPtr,  and  defProcPtr. 

paramTableDesc     Indicates  the  type  of  reference  stored  in  paramTableRef 

$0000  paramTableRef  contains  a  pointer  to  a  window  template 

$0001  paramTableRef  contains  a  handle  to  a  window  template 

$0002  paramTableRef  contains  the  resource  ID  of  a  window  template 

paramTableRef      Reference  to  a  window  template.  The  paramTableDesc  field  defines 
the  type  of  reference  stored  here.  The  resourceType  field  defines  the 
resource  type  for  the  template.  The  template  must  comply  with  the 
format  specification  of  resource  type  rwindParami  or 
rwindParam2  (even  if  the  template  is  not  stored  as  a  resource).  See 
Appendix  E,  "Resource  Types,"  in  this  book  for  information  on  the 
format  and  content  of  these  resources. 
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resourceType         Specifies  the  type  of  window  template  referred  to  by  paramTableRef. 
This  value  should  be  set  correctly  even  if  paramTableRef  'does  not 
contain  a  resource  ID.  Valid  values  are: 

$800E  rWindParaml 

$800F  rWindParam2 
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ResizeWindow     $5C0E 

Moves,  resizes,  and  draws  the  window  specified  by  graJPortPtr.  The  rectPtr  parameter  is  a 
pointer  to  the  window's  content  region.  The  hiddenFlag  parameter  is  a  Boolean 
parameter;  a  TRUE  value  specifies  that  those  portions  of  the  window  that  are  covered 
should  not  be  drawn.  If  the  value  is  FALSE,  the  entire  window  is  drawn,  covered  or  not. 

Parameters 

Stack  before  call 


Previous  contents 


hiddenFlag 


rectPtr 


-     gra/PortPtr 


Stack  after  call 


Word— Boolean;  whether  to  hide  covered  area 
Long— Pointer  to  new  content  rectangle 

Long— Pointer  to  window's  GrafPort 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  ResizeWindow (hiddenFlag,  rectPtr, 
grafPortPtr) ; 

Word      hiddenFlag; 

Pointer   rectPtr,  grafPortPtr; 
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StartFrameDrawing     $5A0E 

Sets  up  Window  Manager  data  to  draw  a  window  frame.  Should  be  called  only  by  window 
definition  procedures.  Must  be  balanced  by  a  call  to  EndFrameDrawing  when  drawing  is 
completed. 


Parameters 

Stack  before  call 

Previous  contents 

-     windowPtr    - 

Long— Pointer  to  window  to  draw 

<— SP 

Stack  after  call 

Previous  contents 

<— SP 

Errors                  None 

C                               extern  pascal  void  StartFrameDrawing (windowPtr) ; 

Poin 

ter        windowPtr; 
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TaskMasterContent     $5D0E 

Internal  routine  that  handles  events  inside  the  content  region  of  a  window.  TaskMaster 
invokes  this  routine  if  the  tmcontentcontrois  bit  of  the  taskMask  field  of  the  task 
record  is  set  to  1.  Your  program  should  never  issue  this  call. 

Pseudo-code: 

if  tmContentControls  in  wmTaskMask  =  1 

if  mousedown  in  content  region  of  frontmost  window 

set  wmTaskData2,  wmTaskData3,  and  wmTaskData4  to  $00000000 

call  FindControl 

put  resulting  partCode  into  low-order  word  of  wmTaskData3 

put  controlHandle  into  wmTaskData2 

if  partCode  <>  0 

call  GetCtllD 

put  resulting  control  ID  into  wmTaskData4 
call  TrackControl  with  actionProcPtr  set  to  $FFFFFFFF 
if  result  <>  0  or  part  code  corresponds  to  scroll  bar 
put  resulting  partCode  into  high-order  word  of 

wmTaskData3 
if  the  control  is  a  check  box  or  radio  button 

Set  or  clear  the  value,  as  appropriate 
endif 

return (wlnControl) 
endif 

set  low  word  of  wmTaskData  =  wlnControl 
return  (nullEvt) 
endif 
else 

set  wmTaskData  =  pointer  to  window 
return (wlnContent) 
endif 
endif 

TaskMasterContent  calls  FindControl.  If  the  user  did  not  press  the  button  in  a 
control,  then  the  routine  returns  a  result  code  of  wmcontent,  indicating  that  the  mouse 
is  in  the  content  region  of  the  window. 

If  the  user  did  press  the  mouse  button  in  a  control,  TaskMasterContent  calls 
TrackControl,  directing  the  Control  Manager  to  use  the  appropriate  action  procedure 
for  the  control. 
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When  TrackControi  returns,  TaskMasterContent  examines  the  part  code.  If  the 
part  code  is  set  to  0,  then  the  user  decided  not  to  use  the  control  (released  the  mouse 
button  outside  the  control).  TaskMasterControi  returns  a  result  code  of  nuiiEvt 
($0000). 

If  the  part  code  is  non-zero,  then  the  user  released  the  mouse  button  within  a  control. 
TaskMasterContent  returns  a  result  code  of  wlnControl,  wmTaskData2  contains 
the  control  handle,  wmTaskData3  (low-order  word)  contains  the  part  code  identifying 
the  control  in  which  the  user  pressed  the  mouse  button,  wmTaskData3  (high-order  word) 
contains  the  part  code  identifying  the  control  where  the  user  released  the  mouse  button, 
and  wmTaskData4  contains  the  control  ID  (if  there  is  one  defined). 
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TaskMasterDA    $5F0E 

This  call  is  the  TaskMaster  entry  point  for  desk  accessories.  Your  program  passes  event 
information  obtained  from  the  Desk  Manager. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


eventMask 


-      taskRecPtr     - 


Stack  after  call 


Word— Space  for  result 
Word— Not  used 

Long— Pointer  to  extended  Task  Record 

<— SP 


Previous  contents 


taskCode 


Errors 
C 


None 


Word— TaskMaster  result  code 
<— SP 


extern  pascal  Word  TaskMasterDA (eventMask, 
taskRecPtr)  ; 
Pointer     taskRecPtr; 


Word 


eventMask; 
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TaskMasterKey    $5E0E 

Internal  routine  that  handles  keystroke  events  inside  the  content  region  of  a  window. 
Your  program  should  never  issue  this  call. 

Pseudo-code: 

if  tmMenuKey  in  wmTaskMask  =1 

if  wmTaskData  =  0       (menu  did  not  take  keystroke) 
if  tmlnactive  in  wmTaskMask  =1 

if  high  word  of  wmTaskData  <>  0 

set  low  word  of  wmTaskData  =  0 

set  high  word  of  wmTaskData  =  ID  of  selected 

inactive  menu  item 
return  (wlnActMenu) 
endif 

goto  CheckControls 
endif 
else  (menu  did  take  keystroke) 

if  low  word  of  wmTaskData  >  255 

if  tmControlMenu  in  wmTaskMask  =  1 

Call  SendEventToCtl  with  targetOnlyFlag  =  TRUE 
if  result  <>  0 

set  wmTaskData2  =  handle  of  control  that 

took  keystroke 
set  wmTaskData3  =  result  code  from  defProc 
set  wmTaskData4  =  ID  of  control  that  took 

keystroke 
dim  the  menu  title  for  selected  menu  item 
set  low  word  of  wmTaskData  = 

wlnControlMenu 
return  (nullEvt) 
endif 
set  low  word  of  wmTaskData  =  ID  of  selected  menu 

item 
set  high  word  of  wmTaskData  =  ID  of  menu  from 

which  selection  was  made 
return  (wlnMenuBar) 
endif 
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elseif  low  word  of  wmTaskData  <  250 
if  tmOpenNDA  in  wmTaskMask  =  0 

set  low  word  of  wmTaskData  =  ID  of  selected  menu 

item 
set  high  word  of  wmTaskData  =  ID  of  menu  from 

which  selection  was  made 
return  (wlnDeskltem) 
endif 

call  OpenNDA 

dim  menu  title  for  selected  menu  item 
set  low  word  of  wmTaskData  =  wlnDeskltem 
return  (nullEvt) 
elseif  tmSpecial  of  wmTaskMask  =  0 

set  low  word  of  wmTaskData  =  ID  of  selected  menu  item 
set  high  word  of  wmTaskData  =  ID  of  menu  from  which 

selection  was  made 
return  (wlnSpecial) 
elseif  top  window  is  an  application  window 
if  tmControlMenu  of  wmTaskMask  =  1 

call  SendEventToCtl  with  targetOnlyFlag  =  TRUE 
if  result  <>  0 

set  wmTaskData2  =  handle  of  control  that 

took  keystroke 
set  wmTaskData3  =  result  code  from  defProc 
set  wmTaskData4  =  ID  of  control  that  took 

keystroke 
dim  the  menu  title  for  selected  menu  item 
set  low  word  of  wmTaskData  = 

wlnControlMenu 
return  (nullEvt) 
endif 
endif 

set  low  word  of  wmTaskData  =  ID  of  selected  menu  item 
set  high  word  of  wmTaskData  =  ID  of  menu  from  which 

item  was  selected 
return  (wlnSpecial) 
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elseif  low  word  of  wmTaskData  =  250,  251,  252,  253,  or  254 
call  SystemEdit 
if  SystemEdit  returns  FALSE 

set  low  word  of  wmTaskData  =  ID  of  selected  menu 

item 
set  high  word  of  wmTaskData  =  ID  of  menu  from 

which  item  was  selected 
return  (wlnSpecial) 
endif 

dim  menu  title  for  menu  item. that  was  selected 
set  low  word  of  wmTaskData  =  wCalledSysEdit 
return  (nullEvt) 
elseif  low  word  of  wmTaskData  =  255 

call  CloseNDAbyWinPtr  for  top  window 
dim  menu  title  for  menu  item  that  was  just  selected 
set  low  word  of  wmTaskData  =  wClosedNDA 
return  (nullEvt) 
endif 
endif 
endif 

CheckControls : 

if  tmControlKey  in  wmTaskMask  =  1 

set  wmTaskData2,  wmTaskData3,  and  wmTaskData4  =  0 
if  there  is  a  front  window 

call  SendEventToCtl  with  targetOnlyFlag  =  FALSE 
if  result  <>  0 

set  wmTaskData2  =  handle  of  control  that  took  the 

keystroke 
set  wmTaskData3  =  result  from  defProc 
set  wmTaskData4  =  ID  of  control  that  took  the 

keystroke 
set  wmTaskData  =  window  containing  control 
if  control  is  a  check  box  or  radio  button 

set  the  ctlValue  for  the  control 
endif 

return  (wlnControl) 
endif 
endif 

return  (keyDownEvt  or  autoKeyEvt) 
endif 
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TaskMasterKey  first  checks  to  see  if  menu  keys  are  to  be  passed  to  the  Menu  Manager. 
If  so,  TaskMasterKey  calls  MenuKey.  If  the  user  entered  a  menu  keystroke,  MenuKey 
handles  it  and  TaskMasterKey  returns  control  to  the  calling  application. 

If  the  user  did  not  enter  a  menu  key  equivalent  or  if  keystrokes  are  not  to  be  passed  to 
the  Menu  Manager,  TaskMasterKey  looks  for  a  control  in  the  active  window  that  wants 
the  keystroke.  If  a  control  takes  the  event,  TaskMasterKey  returns  nuiiEvt  to  the 
calling  application.  Otherwise,  TaskMasterKey  returns  keyDownEvt,  indicating  that 
the  keystroke  is  for  the  application. 


GDRPrivate         $540E 

This  is  an  internal  Window  Manager  call;  your  program  should  never  issue  this  call. 
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Error  messages 

This  section  documents  the  error  numbers  and  accompanying  messages  produced  by  the 
Errorwindow  tool  call.  For  each  error  number,  the  following  table  specifies  the  message 
text  displayed  in  the  dialog  box,  the  icon  shown,  and  the  button(s)  available  for  the  user 
to  press.  Any  required  substitution  strings  are  shown  in  the  message  text. 

Error  (Hoc) Message Icon Button 

$00  No  error  occurred. 

$01  Bad  system  call  number. 

$04  Invalid  parameter  count. 

$07  GS/OS  already  active. 

$10  Device  not  found. 

$11  Invalid  device  number. 

$20  Bad  request  or  demand. 

$21  Bad  control  or  status  code. 

$22  Bad  call  parameter. 

$23  Character  device  not  open. 

$24  Character  device  already  open. 

$25  Interrupt  table  full. 

$26  Resources  not  available. 

$27  I/O  error. 

$28  Device  not  connected. 

$29  Driver  is  busy  and  not  available. 

$2B  Device  is  write  protected. 

$2C  Invalid  byte  count. 

$2D  Invalid  block  number. 

$2E  Disk  has  been  switched. 

$2F  Device  off-line/no  media  present. 

$40  Invalid  pathname  syntax. 

$43  Invalid  reference  number. 

$44  Subdirectory  does  not  exist. 

$45  Volume  not  found. 

$46  File  not  found. 

$47  Duplicate  pathname. 

$48  Volume  full. 

$49  Volume  directory  full. 
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None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 

None 

OK 
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$4A         Version  error.  None  OK 

$4B         Bad  storage  type.  None  OK 

$4C         End  of  file  encountered.  None  OK 

$4D         Position  out  of  range.  None  OK 

$4E        Access  not  allowed.  None  OK 

$4F         Buffer  too  small.  None  OK 

$50         File  is  already  open.  None  OK 

$51         Directory  error.  None  OK 

$52         Unknown  volume  type.  None  OK 

$53         Parameter  out  of  range.  None  OK 

$54       out  of  memory.  None  OK 

$57         Duplicate  volume  name.  None  OK 

$58         Not  a  block  device.  None  OK 

$59         Specified  level  is  outside  legal  range 

None  OK 

$5A         Block  number  too  large.  None  OK 

$5B         Invalid  pathnames  for  change_path.   None  OK 

$5C         Not  an  executable  file.  None  OK 

$5D         Operating  system  not  supported.     None  OK 

$5F         Stack  overflow.  None  OK 

$60         Data  unavailable.  None  OK 

$61         End  of  directory  has  been  reached.   None  OK 

$62         invalid  FST  call  class.  None  OK 

$63         File  does  not  contain  requested  resource. 

None  OK 
$64                      Specified  FST  is  not  present  in  system 

None  OK 
$65         FST  does  not  handle  this  type  of  call 

None  OK 
$66                      FST  handled  call,  but  result  is  weird 

None  OK 

$67         Internal  error.  None  OK 

$68         Device  list  is  full.  None  OK 

$69         Supervisor  list  is  full.  None  OK 

$70         Cannot  expand  file,  resource  already  exists. 

None  OK 
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$71         Cannot  add  resource  fork  to  this  type  of  file. 

None  OK 

$72  unknown  error:  [error string.  None  Cancel 

$80  Error  creating  the  new  directory:  [reason String. 

Stop  Cancel 

$81  Error  saving  the  file:  [reason string.       Stop  Cancel 

$82  Insufficient  access  privileges  to  open  that   folder. 

Stop  OK 

$83  The   selected  folder  cannot  be  opened:  [reason String. 

Stop  Cancel 

$84  You  cannot   replace  a   folder  with  a   file. 

Stop  Cancel 

$85  That   file  already  exists.  Stop  Cancel 

Replace 
$86  Insufficient  memory  to  perform  that   operation. 

About  [number string  additional  needed  Stop  Cancel 

$87  Initialization  failed:    Disk  write  protected. 

Stop  Cancel 

$88  The  pathname  is  too  long.  Stop  OK 

$89  The  disk  is  write  protected.  Caution  Cancel 

■$8A  The  disk  is  full.  Stop  Cancel 

$8B  The  disk  directory  is   full.  Stop  Cancel 

$8C  The  file  is  copy-protected  and  can't  be  copied. 

Stop  Cancel 

$8D  Memory  is  full.  Stop  OK 

$8E  There  isn't  enough  memory  remaining  to  complete  this 

operation.    Please  close   some  windows  and  try  again. 

Stop  OK 

$8F  The  item  is  locked  and  can't  be  renamed. 

Stop  Cancel 

$90  An  I/O  error  has  occurred  while  using  the  disk. 

Stop  Cancel 

$91  This   disk  seems  to  be  damaged 

$92  Not  a  ProDOS  disk. 

$93  No  on-line  volumes  can  be  found. 

$94  insert  the  disk:  [name string. 


Stop 

Cancel 

Stop 

OK 

Stop 

OK 

Swap 

Cancel 
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Appendix  E  Resource  Types 


This  appendix  documents  the  format  and  content  of  standard  resources 
used  by  the  Apple  IIGS  toolbox.  The  resources  are  discussed  in 
alphabetical  order  by  resource  type  name. 
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rAlertString    $8015 

Figure  E-l  defines  the  layout  of  resource  type  rAlertString  ($8015).  Resources  of  this 
type  define  the  data  for  Alert  Windows  to  be  displayed  by  the  Aiertwindow  Window 
Manager  tool  call.  For  more  complete  information  on  Alert  Window  definitions,  see 
Chapter  52,  "Window  Manager  Update,"  earlier  in  this  book. 


■    Figure  E-l       Alert  string,  type  rAlertString  ($8015) 

Aiertwindow  accepts  a  reference  to  a  string  that  contains  its  message,  and  a  reference 
to  an  array  of  substitution  strings.  The  substitution  strings  can  be  any  of  seven  standard 
strings  (such  as  "OK",  "Continue",  and  so  on)  or  can  be  specified  by  the  application  and 
stored  in  the  buffer  to  which  the  substitution-string  pointer  refers. 


$00 1  | 

'■  alertstring  '■   Array 


alertstring      Defines  the  alert  message  to  be  displayed.  Contents  of  this  string  must 
comply  with  the  rules  for  Alert  Window  definitions  documented  in 
Chapter  52,  "Window  Manager  Update,"  earlier  in  this  book. 
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rControlList         $8003 

Figure  E-2  defines  the  layout  of  resource  type  rControlList  ($8003).  The  Control 
Manager  stores  lists  of  resource  IDs  in  resources  of  this  type. 


Figure  E-2       Control  List,  type  rControlList  ($8003) 


$00  |  J 

:  ctiList  :  Array  of  longs 


ctiList  List  of  resource  IDs  for  control  template  definitions.  The  last  entry 

must  be  set  to  NIL. 
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rControlTemplate     $8004 

Resources  of  type  rControlTemplate  ($8004)  define  control  templates,  used  with  the 
Control  Manager  NewControi2  tool  call  to  create  controls.  You  fill  a  type 
rControlTemplate  resource  according  to  the  needs  of  the  particular  control  you  want 
to  create.  The  system  distinguishes  between  different  control  templates  by  examining  the 
procRef  field  in  the  standard  header  portion  that  precedes  each  template. 
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Control  template  standard  header 

Each  control  template  contains  the  standard  header,  which  consists  of  seven  fields. 
Following  that  header,  some  templates  have  additional  fields,  which  further  define  the 
control  to  be  created.  The  format  and  content  of  the  standard  template  header  is  shown 
in  Figure  E-3. 

Custom  control  definition  procedures  establish  their  own  item  template  layout.  The  only 
restriction  placed  on  these  templates  is  that  the  standard  header  be  present  and  well 
formed.  Custom  data  for  the  control  procedure  may  follow  the  standard  header. 


Figure  E-3       Control  template  standard  header 


$00 

pCount              — 

Word 

$02 

ID                  - 

Long 

$06 

rect 

Rectai 

$0E 

procRef              — 

Long 

$12 

flag                 - 

Word 

$14 

moreFlags           — 

Word 

$16 

refCon               - 

Long 

pCount 


Count  of  parameters  in  the  item  template,  not  including  the  pCount 
field.  Minimum  value  is  6,  maximum  value  varies  depending  upon  the 
type  of  control  template. 
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ID 


rect 


procRef 


Sets  the  ctiiD  field  of  the  control  record  for  the  new  control.  The 
ctiiD  field  may  be  used  by  the  application  to  provide  a 
straightforward  mechanism  for  keeping  track  of  controls.  The  control 
ID  is  a  value  assigned  by  your  application,  which  the  control  "carries 
around"  for  your  convenience.  Your  application  can  use  the  ID,  which 
has  a  known  value,  to  identify  a  particular  control. 

Sets  the  ctiRect  field  of  the  control  record  for  the  new  control. 
Defines  the  boundary  rectangle  for  the  control. 

Sets  the  ctiProc  field  of  the  control  record  for  the  new  control.  This 
field  contains  a  reference  to  the  control  definition  procedure  for  the 
control.  The  value  of  this  field  is  either  a  pointer  to  a  control 
definition  procedure,  or  the  ID  of  a  standard  routine.  The  standard 
values  are: 


simpleButtonControl 

$80000000 

Simple  button 

checkControl 

$82000000 

Check  box 

iconButtonControl 

$07FF0001 

Icon  button 

editLineControl 

$83000000 

LineEdit 

listControl 

$89000000 

List 

pictureControl 

$8D000000 

Picture 

popUpControl 

$87000000 

Pop-up 

radioControl 

$84000000 

Radio  control 

scrollBarControl 

$86000000 

Scroll  bar 

growControl 

$88000000 

Size  box 

statTextControl 

$81000000 

Static  Text 

editTextControl 

$85000000 

TextEdit 
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flag  A  word  used  to  set  both  ctiHiiite  and  ctinag  in  the  control 

record  for  the  new  control.  Since  this  is  a  word,  the  bytes  for 
ctiHiiite  and  ctiFlag  are  reversed.  The  high-order  byte  of  flag 
contains  ctiHiiite,  while  the  low-order  byte  contains  ctiFlag. 
The  bits  in  flag  are  mapped  as  follows: 

Highlight  bits  8-15  Indicates  highlighting  style: 

0  Control  active,  no  highlighted 

parts 
1-254    Part  code  of  highlighted  part 
255       Control  inactive 

Invisible  bit  7         Governs  visibility  of  control: 

0  -  Control  visible 

1  -  Control  invisible 

Variable  bits  0-6    Values  and  meaning  depends  upon 

control  type 
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moreFiags  Used  to  set  the  ctiMoreFiags  field  of  the  control  record  for  the 

new  control. 

The  high-order  byte  is  used  by  the  Control  Manager  to  store  its  own 
control  information.  The  low-order  byte  is  used  by  the  control 
definition  procedure  to  define  reference  types. 

The  defined  Control  Manager  flags  are: 


fCtlTarget  $8000 
fCtlCanBeTarget  $4000 
fCtlWantEvents   $2000 


fCtlProcRefNotPtr 


$1000 


fCtlTellAboutSize 


$0800 


fCtllsMultiPart      $0400 


If  set  to  1,  this  control  is  currently  the  target  of  any 

typing  or  editing  commands. 

If  set  to  1  then  this  control  can  be  made  the  target 

control. 

If  set  to  1  then  this  control  can  be  called  when  events 

are  passed  via  the  sendEventToCti  Control 

Manager  call.  Note  that,  if  the  f  ctiCanBeTarget 

flag  is  set  to  1,  this  control  will  receive  events  sent  to 

it  regardless  of  setting  of  this  flag. 

If  set  to  1,  then  Control  Manager  expects  ctiProc 
to  contain  the  ID  of  a  standard  control  procedure.  If 
set  to  0,  then  c  tip  roc  contains  a  pointer  to  the 
custom  control  procedure. 

If  set  to  1,  then  this  control  needs  to  be  notified 
when  the  size  of  the  owning  window  has  changed. 
This  flag  allows  custom  control  procedures  to  resize 
their  associated  control  images  in  response  to 
changes  in  window  size. 

If  set  to  1,  then  this  is  a  multipart  control.  This  flag 
allows  control  definition  procedures  to  manage  multi- 
part controls  (necessary  since  the  Control  Manager 
does  not  know  about  all  the  parts  of  a  multi-part 
control). 
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The  low-order  byte  uses  the  following  convention  to  describe 
references  to  color  tables  and  titles  (note,  though,  that  some  control 
templates  do  not  follow  this  convention): 

titieisPtr  $00  Title  reference  is  by  pointer 

titieisHandie  $01  Title  reference  is  by  handle 

titieisResource  $02  Title  reference  is  by  resource  ID 

coiorTabieisPtr  $00  Color  table  reference  is  by  pointer 

coiorTabieisHandie        $04  Color  table  reference  is  by  handle 
coiorTabieisResource    $08  Color  table  reference  is  by  resource  ID 

ref  Con  Used  to  set  the  ctiRef  Con  field  of  the  control  record  for  the  new 

control.  Reserved  for  application  use. 
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Keystroke  equivalent  information 

Many  of  these  control  templates  allow  you  to  specify  keystroke  equivalent  information 
for  the  associated  controls.  Figure  E-4  shows  the  standard  format  for  that  keystroke 
information. 


Figure  E-4       Keystroke  equivalent  record  layout 


$00 

keyl 

Byte 

$01 

key2 

Byte 

$02 

—      keyModifiers      — 

Word 

$04 

—       keyCareBits       — 

Word 

keyl 
key2 


keyModifiers 


keyCareBits 


This  is  the  ASCII  code  for  the  upper  or  lower  case  of  the  key 
equivalent. 

This  is  the  ASCII  code  for  the  lower  or  upper  case  of  the  key 
equivalent.  Taken  with  keyl,  this  field  completely  defines  the  values 
against  which  key  equivalents  will  be  tested.  If  only  a  single  key  code 
is  valid,  then  set  keyl  and  key2  to  the  same  value. 

These  are  the  modifiers  that  must  be  set  to  1  in  order  for  the 
equivalence  test  to  pass.  The  format  of  this  flag  word  corresponds  to 
that  defined  for  the  event  record  in  Chapter  7,  "Event  Manager,"  in 
Volume  1  of  the  Toolbox  Reference.  Note  that  only  the  modifiers  in  the 
high-order  byte  are  used  here. 

These  are  the  modifiers  that  must  match  for  the  equivalence  test  to 
pass.  The  format  for  this  word  corresponds  to  that  for 
keyModifiers.  This  word  allows  you  to  discriminate  between 
double-modified  keystrokes.  For  example,  if  you  want  Control-7  to 
be  an  equivalent,  but  not  Option-Control-7,  you  would  set  the 
controlKey  bit  in  keyModifiers  and  both  the  optionKey  and  the 
controlKey  bits  in  keyCareBits  to  1.  If  you  want  Return  and  Enter 
to  be  treated  the  same,  the  keyPad  bit  should  be  set  to  0. 


E-10      Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Simple  button  control  template 

Figure  E-5  shows  the  template  that  defines  a  simple. button  control. 

■    Figure  E-5       Item  template  for  simple  button  controls 


$00  _ 


$02  _ 


$06 
$0E 

$12 
$14 
$16 

$1A 

$1E 

$22 


pCount 


—  moreFlags 


flag 


titleRef 


Word— Parameter  count  for  template:  7, 8,  or  9 
Long— Application-assigned  control  ID 


rect  :  Rectangle— Boundary  rectangle  for  control 


procRef  -    Long— simpleButtonControl=$80000000 


"colorTableRef 


Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 


refcon  -   Long— Application-defined  value 


Long— Reference  to  title  for  button 


Long— Reference  to  color  table  for  control  (optional) 


•keyEquivaient      \  Block,  6  bytes— Keystroke  equivalent  data  (optional) 
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Defined  bits  for  flag  are 


Reserved 

bits  &-15 

ctllnvis 

bit  7 

Reserved 

bits  2-6 

Button  type 

bits  0-1 

Defined  bits  formoreFiags  are 


fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fCtlTellAboutSize 

bit  11 

Reserved 

bits  4-10 

Color  table  reference 

bits  2-3 

Title  reference 


bits  0-1 


Must  be  set  to  0 
invisible,  0= visible 
Must  be  set  to  0 
Describes  button  type: 

0  =  single-outlined  round-cornered  button 

1  -  bold-oudined  round-cornered  button 

2  =  single-outlined  square-cornered  button 

3  =  single-outlined  square-cornered  drop-shadowed 
button 


Must  be  set  to  0 

Must  be  set  to  0 

Set  to  1  if  button  has  keystroke  equivalent 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef .  See 

Chapter  4,  "Control  Manager,"  in  Volume  1  of  the 

Toolbox  Reference  for  the  definition  of  the  simple 

button  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  title  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  title  reference  is  resource  ID 
11 -invalid  value 


keyEquivaient  Keystroke  equivalent  information  stored  at  key  Equivalent  is 
formatted  as  shown  in  Figure  E-4. 
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Check  box  control  template 

Figure  E-6  shows  the  template  that  defines  a  check  box  control. 


Figure  E-6       Control  template  for  check  box  controls 

Word— Parameter  count  for  template:  8, 9,  or  10 
Long— Application-assigned  control  ID 

:  Rectangle— Boundary  rectangle  for  control 

Long—  checkBoxControl  =$82000000 

Word— Highlight  and  control  flags  for  control 
Wad— Additional  control  flags 

Long— Application-defined  value 

Long— Reference  to  title  for  box 

Word— Initial  box  setting:  0  for  clear,  1  for  checked 

Long— Reference  to  color  table  for  control  (optional) 


$00 

pCount 

- 

$02 

ID 

_ 

- 

$06 

rect 

$0E 

— 

procRef 

- 

~ 

$12 

flag 

- 

$14 

- 

moreFlags 

- 

$16 

_ 

re f Con 

- 

— 

$1A 

— 

_ 

- 

titleRef 

- 

— 

$1E 

initial Value 

- 

$20 



_ 

- 

*colorTableRef 

- 

- 

- 

$24 

i 

*key£quivalent 

i 

Defined  bits  for  flag  are 


Reserved 

ctllnvis 

Reserved 


bits  8-15     Must  be  set  to  0 
bit  7  1-invisible,  0=visible 

bits  0-6      Must  be  set  to  0 
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Defined  bits  formoreFiags  are 

fCtlTarget  bit  15 
fCtlCanBeTarget  bit  14 
fCtlWantsEvents  bit  13 
fCtlProcNotPtr  bit  12 
fCtlTellAboutSize 

Reserved  bits  4-10 

Color  table  reference    bits  2-3 


Must  be  set  to  0 

Must  be  set  to  0 

Set  to  1  if  check  box  has  keystroke  equivalent 

Must  be  set  to  1 

bit  11  Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef  (see 

Chapter  4,  "Control  Manager,"  in  Volume  1  of  the 

Toolbox  Reference  for  the  definition  of  the  check  box 

color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Tide  reference  bits  0-1       Defines  type  of  tide  reference  in  titieRef : 

00  -  tide  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  tide  reference  is  resource  ID  . 
11 -invalid  value 

key-Equivalent  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  E-4. 
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Icon  button  control  template 

Figure  E-7  shows  the  template  that  defines  an  icon  button  control.  For  more  information 
about  icon  button  controls,  see  "Icon  button  control"  in 
Chapter  28,  "Control  Manager  Update,"  earlier  in  this  book. 


Figure  E-7       Control  template  for  icon  button  controls 


$00 
$02 
$06 
$0E 

$12 
$14 
$16 

$1A 

$1E 

$22 

$26 
$28 


pcount  -   Word— Parameter  count  for  template:  7, 8, 9, 1 0,  or  1 1 


-   Long— Application-assigned  control  ID 


rect 


I  Rectangle— Boundary  rectangle  for  control 


—     moreFlags 


procRef 


flag 


iconRef 


*titleRef     - 


•colorTableRef 


-    *displayMode    — 


Long— iconButtonControl  =$07FF0001 

Word— Highlight  and  control  flags  for'control 
Wad— Additional  control  flags 

Long— Application-defined  value 

Long— Reference  to  icon  for  control 

Long— Reference  to  title  for  control  (optional) 

Long— Reference  to  color  table  for  control  (optional) 
Word— Bit  flag  controlling  icon  appearance  (optional) 


♦keyEquivaient       \  Block,  6  bytes— Key  equivalent  information  (optional) 
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Defined  bits  for  flag  are 


ctlHilite 

bits  8-15 

ctllnvis 

bit  7 

Reserved 

bits  5-6 

showBorder 

bit  2 

buttonType 

bits  0-1 

Defined  bits  formoreFiags  are 

fCtlTarget  bit  15 

fCtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 


fCtlTellAboutSize 


Reserved 
Icon  reference 


bit  11 
bits  6-10 
bits  4-5 


Color  table  reference    bits  2-3 


Title  reference 


bits  0-1 


Sets  the  ctlHilite  field  of  the  control  record 

1 -invisible,  0=visible 

Must  be  set  to  0 

1-No  border,  0=Show  border 

Defines  button  type: 

00  -  single-outlined  round-cornered  button 

01  -  bold-outiined  round-cornered  button 

10  -  single-oudined  square-cornered  button 

11  -  single-oudined  square-cornered  and  drop- 
shadowed  button 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 

Must  be  set  to  0 
Must  be  set  to  0 
Defines  type  of  icon  reference  in  iconRef : 

00  -  icon  reference  is  pointer 

01  -  icon  reference  is  handle 

10  -  icon  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  reference  in  coiorTabieRef ;  the 
color  table  for  an  icon  button  is  the  same  as  that  for  a 
simple  button  (see  Chapter  4,  "Control  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  for  the  definition 
of  the  simple  button  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  tide  reference  in  titieRef : 

00  -  tide  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  tide  reference  is  resource  DO 
11 -invalid  value 
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titleRef 


displayMode 


Reference  to  the  title  string,  which  must  be  a  Pascal  string.  If  you  are 
not  using  a  title  but  are  specifying  other  optional  fields,  set 
moreFiags  bits  0  and  1  to  0,  and  set  this  field  to  zero. 

Passed  direcdy  to  the  Drawicon  routine,  and  defines  the  display 
mode  for  the  icon.  The  field  is  defined  as  follows  (for  more 
information  on  icons,  see  Chapter  17,  "QuickDraw  II  Auxiliary,"  in 
Volume  2  of  the  Toolbox  Reference): 

Defines  the  background  color  to  apply  to  black  part 

of  black-and-white  icons. 

Defines  the  foreground  color  to  apply  to  white  part 

of  black-and-white  icons. 

Must  be  set  to  0 

1=AND  light-gray  pattern  to  image  being  copied 

0-Don't  AND  the  image 

1-Copy  light-gray  pattern  instead  of  image 

0=Don't  copy  light-gray  pattern 

1 -Invert  image  before  copying 

0=Don't  invert  image 

Color  values  (both  foreground  and  background)  are  indexes  into  the 
current  color  table.  See  Chapter  16,  "QuickDraw  II,"  in  Volume  2  of  the 
Toolbox  Reference  for  details  about  the  format  and  content  of  these 
color  tables. 

keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  E-4. 


Background  Color 

bits  12-: 

Foreground  Color 

bits  8-1: 

Reserved 

bits  3-7 

of fLine 

bit  2 

openlcon 

bitl 

selectedlcon 

bitO 
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LineEdit  control  template 

Figure  E-8  shows  the  template  that  defines  a  LineEdit  control.  For  more  information 
about  LineEdit  controls,  see  "LineEdit  control"  in  Chapter  28,  "Control  Manager  Update," 
earlier  in  this  book. 


Figure  E-8       Control  template  for  LineEdit  controls 


$00 
$02 

$06 
$0E 

$12 
$14 
$16 

$1A 
$1C 


pCount 


ID 


procRef 


flag 


moreFlags 


Word— Parameter  count  for  template:  8 
Long— Application-assigned  control  ID 


\  Rectangle— Boundary  rectangle  for  control 


Long— editLineControl  -$83000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 


re  f  con  -   Long— Application-defined  value 

maxsize  -   Word— Maximum  length  of  input  line  (in  bytes) 

defauitRef       -\  Long— Reference  to  default  text 


Defined  bits  for  flag  are 


Reserved 

bits  8-15 

Must  be  set  to  0 

ctllnvis 

bit  7 

1 -invisible,  0=visible 

Reserved 

bits  0-6 

Must  be  set  to  0 
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Defined  bits  for  moreFiags  are 


fCtlTarget                 bit  15 

Must  be  set  to  0 

fCtlCanBeTarget     bit  14 

Must  be  set  to  1 

fCtlWantsEvents      bit  13 

Must  be  set  to  1 

fCtlProcNotPtr        bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11 

Must  be  set  to  0 

Reserved                    bits  2-10 

Must  be  set  to  0 

Text  reference             bits  0-1 

Defines  type  of  text  reference  in  def  auitRe 

00  -  text  reference  is  pointer 

01  -  text  reference  is  handle 

10  -  text  reference  is  resource  ID 

11 -invalid  value 

maxsize  Specifies  the  maximum  number  of  characters  allowed  in  the  LineEdit 

field.  Valid  values  lie  in  the  range  from  1  to  255. 

The  high-order  bit  indicates  whether  the  LineEdit  field  is  a  password 
field.  Password  fields  protect  user  input  by  echoing  asterisks,  rather 
than  the  actual  user  input.  If  this  bit  is  set  to  1,  then  the  LineEdit  field 
is  a  password  field. 

Note  that  LineEdit  controls  do  not  support  color  tables. 
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List  control  template 

Figure  E-9  shows  the  template  that  defines  a  list  control.  For  more  information  about  list 
controls,  see  "List  control"  in  Chapter  28,  "Control  Manager  Update,"  earlier  in  this  book. 


Figure  E-9       Control  template  for  list  controls 


$00 
$02 

$06 
$0E 

$12 
$14 
$16 

$1A 
$1C 
$1E 
$20 
$22 

$26 
$28 
$2A 

$2E 


—       flag       — 


—     moreFlags     — 


—  refcon  —   Long— Application-defined  value 


pcount  —   Word— Parameter  count  for  template:  14  or  15 


ID 


liststart 


—   Long— Application-assigned  control  ID 


procRef      — 


listMemSize    — 


listRef      — 


Rectangle— Boundary  rectangle  for  control 

($0E)Long— listControl  =$89000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 


listsize         — |  Word— Number  of  members  in  list 
listview         — I  Word— Number  of  members  visible  in  window 
listType         —|  Word— Type  oflist  entries,  selection  options,  etc. 
Word— First  visible  list  member 


—         listDraw         —   Long— Pointer  to  member  drawing  routine 


listMemHeight     — |  Word— Height  of  each  list  item  (in  pixels) 
Word— Size  of  list  entry  (in  bytes) 


Long— Reference  to  list  of  member  records 


—    *coiorTabieRef    —   Long— Reference  to  color  table  for  control  (optional) 
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Defined  bits  for  flag  are 


Reserved                    bits  8-15 

Must  be  set  to  0 

ctllnvis                     bit  7 

1  "invisible,  0= visible 

Reserved                   bits  0-6 

Must  be  set  to  0 

Defined  bits  for  mo reF lags  are 

fCtlTarget                 bit  15 

Must  be  set  to  0 

f  CtlCanBeTarget     bit  14 

Must  be  set  to  0 

fCtlWantsEvents      bit  13 

Must  be  set  to  0 

fCtlProcNotPtr        bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11 

fCtllsMultiPart      bit  10 

Reserved  bits  4-9 

Color  table  reference    bits  2-3 


List  reference 


bits  0-1 


Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef  (the 

color  table  for  a  List  control  is  described  in 

Chapter  11,  "List  Manager,"  in  Volume  1  of  the 

Toolbox  Reference) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11 -invalid  value 

Defines  type  of  reference  in  listRef  (the  format 

for  a  list  member  record  is  described  in 

Chapter  11,  "List  Manager,"  in  Volume  1  of  the 

Toolbox  Reference) 

00  -  list  reference  is  pointer 

01  -  list  reference  is  handle 

10  -  list  reference  is  resource  ED 
11 -invalid  value 
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listType 

Reserved 

fListScrollBar 


Valid  values  for  listType  are  as  follows: 


fListSelect 


fListString 


bits3— 15     Must  be  set  to  0. 

bit  2  Allows  you  to  control  where  the  scroll  bar  for  the  list  is 

drawn: 

1  -  Scroll  bar  drawn  on  inside  of  boundary  rectangle. 

The  List  Manager  calculates  space  needed,  adjusts 

dimensions  of  boundary  rectangle,  and  resets  this 

flag. 

0  -  Scroll  bar  drawn  on  outside  of  boundary  rectangle, 
bit  1           Controls  type  of  selection  options  available  to  the 

user: 

1  -  Only  single  selection  allowed 

0  -  Arbitrary  and  range  selection  allowed 

bit  0  Defines  the  type  of  strings  used  to  define  list  items: 

1  -  C-strings  ($00-terminated) 
0  -  Pascal  strings 


For  details  on  the  remaining  custom  fields  in  this  template,  see  the  discussion  of  "List 
Controls  and  List  Records"  in  Chapter  11,  "List  Manager,"  of  Volume  1  of  the  Toolbox 
Reference. 
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Picture  control  template 

Figure  E-10  shows  the  template  that  defines  a  picture  control.  For  more  information  about 
picture  controls,  see  "Picture  control"  in  Chapter  28,  "Control  Manager  Update,"  earlier  in 
this  book. 


Figure  E-10      Control  template  for  picture  controls 


$00 
$02 

$06 
$0E 

$12 
$14 
$16 

$1A 


ID 


procRef 


flag 


pcount  -   Word— Parameter  count  for  template:  7 

Long— Application-assigned  control  ID 


-   Word— Highlight  and  control  flags  for  control 


pictureRef 


Rectangle— Boundary  rectangle  for  control 


Long— pictureControl  =$8D0O0OO0 


moreFiags        -   Word— Additional  control  flags 


re  f  con  -   Long— Application-defined  value 

Long-Reference  to  picture  for  control 


Defined  bits  for  flag  are 


ctlHilite 


ctllnvis 

Reserved 


bits  8-15     Specifies  whether  the  control  wants  to  receive  mouse 

selection  events;  the  values  for  ctlHi lite  are  as 

follows: 

0       Control  is  active 

255    Control  is  inactive 
bit  7  1  "invisible,  0=visible 

bits  0-6      Must  be  set  to  0 
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Defined  bits  for  moreFiags  are 

f  CtlTarget                 bit  15 

Must  be  set  to  0 

fCtlCanBeTarget     bit  14 

Must  be  set  to  0 

fCtlWantsEvents      bit  13 

Must  be  set  to  0 

fCtlProcNotPtr        bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11           Must  be  set  to  0 

Reserved                    bits  2-10 

Must  be  set  to  0 

Picture  reference          bits  0-1 

Define  type  of  picture  reference  in  pictureRef 

00  -  invalid  value 

01  -  reference  is  handle 

10  -  reference  is  resource  ID 

11 -invalid  value 
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Pop-up  control  template 

Figure  E-ll  shows  the  template  that  defines  a  pop-up  control.  For  more  information 
about  pop-up  controls,  see  "Pop-up  control"  in  Chapter  28,  "Control  Manager  Update," 
earlier  in  this  book. 


Figure  E-ll      Control  template  for  pop-up  controls 

Wad— Parameter  count  for  template:  9  or  10 
Long— Application-assigned  control  ID 

Rectangle— Boundary  rectangle  for  control 

Long— popUpCorit  rol =$87000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 


$00 

pCount 

- 

$02 

— 

ID 

- 

$06 

reot 

$0E 

_ 

procRef 

~ 

$12 

flag 

- 

$14 

moreFlags 

- 

$16 

— 

refCon 

: 

$1A 

titleWidth 

- 

$1C 

_ 

menuRef 

- 

— 

$20 

initialValue 

- 

$22 

_ 

*colorTableRef 

- 

~ 

Long— Reference  to  menu  definition 


Word— Item  ID  of  initial  item 
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Defined  bits  for  flag  are 


ctlHilite 


bits  8-15 


ctllnvis 
fType2PopUp 


bit  7 

bit  6 


fDontHiliteTitle  bit  5 


fDontDrawTitle   bit  4 


fDontDrawResult   bit  3 


f  InWindowOnly    bit  2 


Specifies  whether  the  control  wants  to  receive  mouse 
selection  events;  the  values  for  ctlHilite  are  as 
follows: 

0  Control  is  active 
255    Control  is  inactive 
1 -invisible,  0=visible 

Tells  the  Control  Manager  whether  to  create  a  pop-up 
menu  with  white  space  for  scrolling  (see 
Chapter  37,  "Menu  Manager  Update,"  for  details  on 
Type  2  pop-up  menus): 

1  -  Draw  pop-up  with  white  space  (Type  2) 

0  -  Draw  normal  pop-up 

Controls  highlighting  of  the  control  title: 

1  -  Do  not  highlight  title  when  control  is  popped  up 

0  -  Highlight  title 

Allows  you  to  prevent  the  tide  from  being  drawn 
(note  that  you  must  supply  a  title  in  the  menu 
definition,  whether  or  not  it  will  :be  displayed);  if 
titiewidth  is  defined  and  this  bit  is  set  to  1,  then 
the  entire  menu  is  offset  to  the  right  by  titiewidth 
pixels: 

1  -  Do  not  draw  the  title 

0  -  Draw  the  title 

Allows  you  to  control  whether  the  selection  is  drawn 
in  the  pop-up  rectangle: 

1  -  Do  not  draw  the  result  in  the  result  area  after  a 
selection 

0  -  Draw  the  result 

Controls  the  extent  to  which  the  pop-up  menu  can 
grow;  this  is  particularly  relevant  to  Type  2  pop-ups 
(see  Chapter  37,  "Menu  Manager  Update,"  for  details 
on  Type  2  pop-up  menus): 

1  -  Keep  the  pop-up  in  the  current  window 
0  -  Allow  the  pop-up  to  grow  to  screen  size 


f Right JustifyTitle 
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bit  1  Controls  title  justification: 

1  -  Right  justify  the  title;  note  that  if  the  title  is  right 
justified,  then  the  control  rectangle  is  adjusted  to 
eliminate  unneeded  pixels,  the  value  for 
titiewidth  is  also  adjusted 
0  -  Left  justify  the  title 


f Right JustifyResult 
bitO 


Defined  bits  for  moreFiags  are 

fCtlTarget  bit  15 
fCtlCanBeTarget  bit  14 
fCtlWantsEvents  bit  13 

fCtlProcNotPtr   bit  12 

fCtlTellAboutSize 

bit  11 

Reserved  bits  5-10 

Color  table  reference     bits  3-4 


fMenuDeflsText 


Controls  result  justification: 

1  -  Right  justify  the  selection 

0  -  Left  justify  the  selection  titiewidth  pixels  from 

the  left  of  the  pop-up  rectangle. 


Must  be  set  to  0 

Must  be  set  to  0 

Must  be  set  to  1  if  the  pop-up  has  any  keystroke 

equivalents  defined 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef  (the 

color  table  for  a  menu  is  described  in 

Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the 

Toolbox  Reference) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

bit  2  Defines  type  of  data  referred  to  by  menuRef : 

1  -  menuRef  is  a  pointer  to  a  text  stream  in  NewMenu 
format  (see  Chapter  13,  "Menu  Manager,"  in  Volume  1 
of  the  Toolbox  Reference  for  details) 
0  -  menuRef  is  a  reference  to  a  Menu  Template 
(again,  see  Chapter  13,  "Menu  Manager,"  in  Volume  1 
of  the  Toolbox  Reference  for  details  on  format  and 
content  of  a  Menu  Template) 
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Menu  reference 


rect 


initialValue 


titleWidth 


menuRef 


bits  0-1       Defines  type  of  menu  reference  in  menuRef  (if 
fMenuDef  is  Text  is  set  to  1,  then  these  bits  are 
ignored): 

00  -  menu  reference  is  pointer 

01  -  menu  reference  is  handle 

10  -  menu  reference  is  resource  ID 

11  -  invalid  value 

Defines  the  boundary  rectangle  for  the  pop-up  and  its  tide,  before  the 
menu  has  been  "popped"  by  the  user.  The  Menu  Manager  will  calculate 
the  lower,  right  coordinates  of  the  rectangle  for  you,  if  you  specify 
those  coordinates  as  (0,0). 

The  initial  value  to  be  displayed  for  the  menu.  The  initial  value  is  the 
default  value  for  the  menu,  and  is  displayed  in  the  pop-up  rectangle  of 
"unpopped"  menus.  You  specify  an  item  by  its  ID,  that  is,  its  relative 
position  within  the  array  of  items  for  the  menu  (see 
Chapter  37,  "Menu  Manager  Update,"  for  information  on  the  layout 
and  content  of  the  pop-up  menu  template).  If  you  pass  an  invalid 
item  ID  then  no  item  is  displayed  in  the  pop-up  rectangle. 

Provides  you  with  additional  control  over  placement  of  the  menu  on 
the  screen.  The  titiewidth  field  defines  an  offset  from  the  left 
edge  of  the  control  (boundary)  rectangle  to  the  left  edge  of  the  pop- 
up rectangle.  If  you  are  creating  a  series  of  pop-up  menus  and  you 
want  them  to  be  vertically  aligned,  you  can  do  this  by  giving  all  menus 
the  same  xl  coordinate  and  titiewidth  value.  You  may  use 
titiewidth  for  this  even  if  you  are  not  going  to  display  the  tide 
(fDontDrawTitle  flag  is  settO  1  in  flag).  If  you  set  titleWidth 
to  0,  then  the  Menu  Manager  determines  its  value  based  upon  the 
length  of  the  menu  tide,  and  the  pop-up  rectangle  immediately  follows 
the  tide  string.  If  the  actual  width  of  your  tide  exceeds  the  value  of 
titiewidth,  results  are  unpredictable. 

Reference  to  menu  definition  (see  Chapter  13,  "Menu  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  and 

Chapter  37,  "Menu  Manager  Update,"  in  this  book  for  details  on  menu 
templates).  The  type  of  reference  contained  in  menuRef  is  defined 
by  the  menu  reference  bits  in  mo  reFi  ags . 
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Radio  button  control  template 

Figure  E-12  shows  the  template  that  defines  a  radio  button  control: 

■    Figure  E-12      Control  template  for  radio  button  controls 


$00 
$02 

$06 
$0E 

$12 
$14 
$16 

$1A 

$1E 
$20 

$24 


pCount 


ID 


Word— Parameter  count  for  template:  8, 9,  or  10 
Long— Application-assigned  control  ID 


\  Rectangle— Boundary  rectangle  for  control 


—  moreFlags 


procRef  -    Long— radioButtonControl  =$84000000 


flag 


re  f  con  -    Long— Application-defined  value 


Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 


titieRef         -   Long— Reference  to  title  for  button 
-      initiaivaiue      -   Word— Initial  setting:  0  for  clear,  1  for  set 
r-     *coiorTabieRef    -|  Long— Reference  to  color  table  for  control  (optional) 


•keyEquivaient      '•  Block,  6  bytes— Keystroke  equivalent  data  (optional) 


Defined  bits  for  flag  are 


Reserved 

ctllnvis 


bits  8-15     Must  be  set  to  0 
bit  7  1  "invisible,  Ovisible 
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Family  number  bits  0-6      Family  numbers  define  associated  groups  of  radio 

buttons;  radio  buttons  in  the  same  family  are  logically 
linked,  that  is,  setting  one  radio  button  in  a  family 
clears  all  other  buttons  in  the  same  family 

Defined  bits  for  moreFiags  are  as  follows: 


fCtlTarget  bit  15 

fCtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 

fCtlTellAboutSize 

bit  11 
Reserved  bits  4-10 

Color  table  reference     bits  2-3 


Must  be  set  to  0 

Must  be  set  to  0 

Set  to  1  if  button  has  keystroke  equivalent 

Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef  (see 

Chapter  4,  "Control  Manager,"  in  Volume  1  of  the 

Toolbox  Reference  for  the  definition  of  the  radio 

button  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
Defines  type  of  tide  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  tide  reference  is  resource  ID 

11  -  invalid  value 

keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  E-4. 


Tide  reference 


bits  0-1 
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Scroll  bar  control  template 

Figure  E-13  shows  the  template  that  defines  a  scroll  bar  control: 


Figure  E-13      Control  template  for  scroll  bar  controls 

Word— Parameter  count  for  template:  9  or  10 
Long— Application-assigned  control  ID 

Rectangle— Boundary  rectangle  for  control 

Long—  scrollControl  =$86000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 

Word— Initial  size  of  displayed  item 
Word— Amount  of  item  initially  visible 
Word— Initial  setting 


$00 

pCount 

- 

$02 

— 

ID 

- 

- 

$06 

rect 

$0E 

— 

procRef 

- 

~ 

$12 

flag 

- 

$14 

moreFlags 

- 

$16 

— 

re f Con 

- 

— 

- 

$1A 

- 

maxsize 

- 

$1C 

viewSize 

- 

$1E 

initialValue 

- 

$20 

_ 

— 

- 

♦colorTableRef 

- 

— 

— 
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Defined  bits  for  flag  are 

Must  be  set  to  0 
l=invisible,  0=visible 
Must  be  set  to  0 

1-horizontal  scroll  bar,  0=vertical  scroll  bar 
1-bar  has  right  arrow,  0-bar  has  no  right  arrow 
1-bar  has  left  arrow,  0=bar  has  no  left  arrow 
1-bar  has  down  arrow,  0-bar  has  no  down  arrow 
1-bar  has  up  arrow,  0-bar  has  no  up  arrow 

Note  that  extraneous  flag  bits  are  ignored,  based  upon  state  of  horscroii  flag.  For 
example,  for  vertical  scroll  bars,  rightFlag  and  lef  tFlag  are  ignored. 


Reserved 

bits  8-15 

ctllnvis 

bit  7 

Reserved 

bits  5-6 

horScroll 

bit  4 

rightFlag 

bit  3 

leftFlag 

bit  2 

downFlag 

bitl 

upFlag 

bitO 

Defined  bits  for  moreFiags  are 

fCtlTarget  bit  15 

fCtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 

fCtlTellAboutSize 

bit  11 
Reserved  bits  4-10 

Color  table  reference     bits  2-3 


Reserved 


bits  0-1 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  colorTableRef(see 

Chapter  4,  "Control  Manager,"  in  Volume  1  of  the 

Toolbox  Reference  and  "Clarifications"  in 

Chapter  28,  "Control  Manager  Update,"  earlier  in  this 

book  for  the  definition  of  the  scroll  bar  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
Must  be  set  to  0 
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Size  box  control  template 

Figure  E-14  shows  the  template  that  defines  a  size  box  control: 

■    Figure  E-14      Control  template  for  size  box  controls 


$00 
$02 

$06 
$0E 

$12 
$14 
$16 

$20 


—  moreFlags 


pCount 


flag 


re f Con 


Word— Parameter  count  for  template:  6  or  7 


-   Long— Application-assigned  control  ID 


'■  Rectangle— Boundary  rectangle  for  control 


prooRef  -   Long— growControl  =$88000000 


Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 


-     *coiorTabieRef    -   Long— Reference  to  color  table  for  control  (optional) 


Defined  bits  for  flag  are 


Reserved 

ctllnvis 

Reserved 

fCallWindowMgr 


bits  &-15     Must  be  set  to  0 

bit  7  1 -invisible,  0=visible 

bits  1-6      Must  be  set  to  0 

bit  0  l=call  Growwindow  and  sizewindow  to  track  this 

control 

0=just  highlight  control 
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Defined  bits  formoreFiags  are 

fCtlTarget  bit  15 

fCtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 

fCtlTellAboutSize 

bit  11 
Reserved  bits  4-10 

Color  table  reference     bits  2-3 


Reserved 


bits  0-1 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 

Must  be  set  to  0 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef  (see 

"Error  Corrections"  in 

Chapter  28,  "Control  Manager  Update,"  earlier  in  this 

book  for  the  definition  of  the  size  box  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
Must  be  set  to  0 
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Static  text  control  template 

Figure  E-15  shows  the  template  that  defines  a  static  text  control.  For  more  information 
about  static  text  controls,  see  "Static  text  control"  in 
Chapter  28,  "Control  Manager  Update,"  earlier  in  this  book. 


Figure  E-15      Control  template  for  static  text  controls 


$00 
$02 

$06 
$0E 

$12 
$14 
$16 

$1A 

$1E 
$20 


-        morenags        -   Word — Additional  control  flags 


ID 


♦textsize 


'just 


pcount  -j  Word— Parameter  count  for  template:  7, 8,  or  9 

Long— Application-assigned  control  ID 


Rectangle— Boundary  rectangle  for  control 


prooRef  -    Long— statTextControl  =$81000000 


flag  -   Word— Highlight  and  control  flags  for  control 


refcon  -   Long— Application-defined  value 


textRef  -   Long— Reference  to  text  for  control 


Word— Text  size  field  (optional) 

Word— Initial  justification  for  text  (optional) 
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Defined  bits  for  flag  are 

Reserved  bits  8-15 

ctiinvis  bit  7 

Reserved  bits  2-6 

f  SubstituteText  bit  1 


fSubTextType 


bitO 


Must  be  set  to  0 

1  invisible,  0=visible 

Must  be  set  to  0 

0=no  text  substitution  to  perform 

l=there  is  text  substitution  to  perform 

0=C  strings 

1 -Pascal  strings 


Defined  bits  for  moreFiags  are 


fCtlTarget                 bit  15 

Must  be  set  to  0 

fCtlCanBeTarget     bit  14 

Must  be  set  to  0 

fCtlWantsEvents     bit  13 

Must  be  set  to  0 

fCtlProcNotPtr        bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11 

Must  be  set  to  0 

Reserved                   bits  2-10 

Must  be  set  to  0 

Text  Reference            bits  0-1 

Defines  type  of  text  reference  in  text  Re  f 

00  -  text  reference  is  pointer 

01  -  text  reference  is  handle 

10  -  text  reference  is  resource  ID 

11 -invalid  value 

textSize 


just 


The  size  of  the  referenced  text  in  characters,  but  only  if  the  text 
reference  in  textRef  is  a  pointer.  If  the  text  reference  is  either  a 
handle  or  a  resource  ID,  then  the  Control  Manager  can  extract  the 
length  from  the  handle. 

The  justification  word  is  passed  on  to  LETextBox2  (see 
Chapter  10,  "LineEdit  Tool  Set,"  in  Volume  1  of  the  Toolbox  Reference 
for  details  on  the  LETextBox2  tool  call),  and  is  used  to  set  the  initial 
justification  for  the  text  being  drawn.  Valid  values  for  just  are 


leftJustify  0 

centerJustify  1 

rightjustify  -1 

fullJustify  2 


Text  is  left  justified  in  the  display  window 
Text  is  centered  in  the  display  window 
Text  is  right  justified  in  the  display  window 
Text  is  fully  justified  (both  left  and  right)  in 
the  display  window 


Static  text  controls  do  not  support  color  tables.  In  order  to  display  text  of  different 
color,  you  must  embed  the  appropriate  commands  into  the  text  string  you  are  displaying. 
See  the  discussion  of  LETextBox2  in  Chapter  10,  "LineEdit  Tool  Set,"  in  Volume  1  of  the 
Toolbox  Reference  for  details  on  command  format  and  syntax. 
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TextEdit  control  template 

Figure  E-16  shows  the  template  that  defines  a  TextEdit  control.  For  more  information 
about  TextEdit  controls,  see  "TextEdit  control"  in  Chapter  28,  "Control  Manager  Update," 
earlier  in  this  book. 


$06 


Figure  E-16      Control  template  for  TextEdit  controls 

pcount  -   Word— Parameter  count  for  template:  7  to  23 

-   Long— Application-assigned  control  ID 

Rectangle— Boundary  rectangle  for  control 

Long— editTextControl  =$85000000 

Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 

Long— Specific  TextEdit  control  flags  (see  below) 
*  indentRect         :  Rectangle— Defines  text  indentation  from  control  rect  (optional) 


rect 

$0E 

procRef 

_ 

— 

$12 

flag 

- 

$14 

moreFlags 

- 

$16 

re f Con 

"~ 

$1A 

_ 

— 

- 

textFlags 

" 

"" 

$1E 

$26  _ 


$2A 
$2C 

$30 


—         *vertflmount 


•vertBar 


•horzBar 


•horzAmount         — 


continued 


Long— Handle  to  vertical  scroll  bar  for  control  (optional) 
Word— Vertical  scroll  amount,  in  pixels  (optional) 
Long— Reserved;  must  be  set  to  NILL  (optional) 
Word— Reserved;  must  be  set  to  0  (optional) 
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continued 

$32 

— 

*styleRef 

- 

~ 

$36 

*textDescriptor 

- 

$38 

— 

♦text Re f 

- 

— 

$3C 

_ 

•textLength 

- 

— 

$40 

— 

•maxChars 

: 

M 

_ 

♦maxLines 

- 

— 

$48 

•maxCharsPerLines 

- 

$4A 

—    *maxHeight    — 

$4C 

_ 

*colorRef 

- 

— 

$50 

*drawMode 

- 

$52 

_ 

*fllterProcPtr 

- 

«_ 

Long— Reference  to  initial  style  information  for  text  (optional) 
Word— Defines  format  of  initial  text  and  textRef  (optional) 
-   Long— Reference  to  initial  text  for  edit  window  (optional) 

Long— Length  of  initial  text  (optional) 

Long— Maximum  number  of  characters  allowed  (optional) 

Long— Reserved;  must  be  set  to  0  (optional) 

Word— Reserved;  must  be  set  to  0  (optional) 
Word— Reserved;  must  be  set  to  0  (optional) 

-|  Long— Reference  to  TextEdit  color  table  (optional) 

Word— QuickDraw  II  text  mode  for  edit  window  (optional) 

Long— Pointer  to  filter  routine  for  this  control  (optional) 


Defined  bits  for  flag  are 


Reserved 

ctllnvis 

Reserved 


bits  8-15     Must  be  set  to  0 
bit  7  1 -invisible,  0= visible 

bits  0-6      Must  be  set  to  0 
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Defined  bits  for  more 

Flags  are 

fCtlTarget 

bit  15 

fCtlCanBeTarget 

bit  14 

fCtlWantsEvents 

bit  13 

fCtlProcNotPtr 

bit  12 

fTellAboutSize 

bit  11 

fCtllsMultiPart     bit  10 
Reserved  bits  4-9 

Color  table  reference     bits  2-3 


Style  reference 


bits  0-1 


Must  be  set  to  0 

Must  be  set  to  1 

Must  be  set  to  1 

Must  be  set  to  1 

If  set  to  1,  a  size  box  will  be  created  in  the  lower-right 

corner  of  the  window.  Whenever  the  control  window 

is  resized,  the  edit  text  will  be  resized  and  redrawn. 

Must  be  set  to  1  | 

Must  be  set  to  0 

Defines  type  of  reference  in  coiorRef ;  the  color 

table  for  a  TextEdit  control  (TECoiorTabie)  is 

described  in  Chapter  49,  "TextEdit,"  in  this  book: 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  style  reference  in  styieRef;  the 
format  for  a  TextEdit  style  descriptor  is  described  in 
Chapter  49,  "TextEdit,"  in  this  book: 

00  -  style  reference  is  pointer 

01  -  style  reference  is  handle 

10  -  style  reference  is  resource  ID 

11  -  invalid  value 


A  Important 


Do  not  set  f  TeliAboutsize  to  1  unless  the  control  also  has  a 
vertical  scroll  bar.  a 


Valid  values  for  textFiags  are 

fNotControl  bit  31 

f  SingleFormat  bit  30 

f  SingleStyle  bit  29 


fNoWordWrap 


bit  28 


Must  be  set  to  0 

Must  be  set  to  1 

Allows  you  to  restrict  the  style  options  available  to 

the  user: 

1  -  Allow  only  one  style  in  the  text 

0  -  Do  not  restrict  the  number  of  styles  in  the  text 
Allows  you  to  control  TextEdit  word  wrap  behavior: 

1  -  Do  not  word  wrap  the  text;  only  break  lines  on  CR 
($0D)  characters 

0  -  Perform  word  wrap  to  fit  the  ruler 
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fNoScroll 


fReadOnly 


f  SmartCutPaste        bit  25 


fTabSwitch 


fDrawBounds 


fColorHilight  bit  22 

fGrowRuler  bit  21 


bit  27         Controls  user  access  to  scrolling: 

1  -  Do  not  allow  either  manual  or  auto-scrolling 

0  -  Scrolling  permitted 

bit  26         Restricts  the  text  in  the  window  to  read-only 

operations  (copying  from  the  window  will  still  be 
allowed): 

1  -  No  editing  allowed 

0  -  Editing  permitted 

Controls  TextEdit  support  for  smart  cut  and  paste 
(see  Chapter  49,  "TextEdit,"  for  details  on  smart  cut 
and  paste  support): 

1  -  Use  smart  cut  and  paste 

0  -  Do  not  use  smart  cut  and  paste 
bit  24         Defines  behavior  of  the  Tab  key  (see 

Chapter  49,  "TextEdit,"  for  details): 

1  -  Tab  to  next  control  in  the  window 

0  -  Tab  inserted  in  TextEdit  document 

bit  23  Tells  TextEdit  whether  to  draw  a  box  around  the  edit 
window,  just  inside  rect;  the  pen  for  this  box  is  two 
pixels  wide  and  one  pixel  high 

1  -  Draw  rectangle 

0  -  Do  not  draw  rectangle 
Must  be  set  to  0. 

Tells  TextEdit  whether  to  resize  the  ruler  in  response 
to  the  user  resizing  the  edit  window;  if  set  to  1, 
TextEdit  will  automatically  adjust  the  right  margin 
value  for  the  ruler: 

1  -  Resize  the  ruler 
0  -  Do  not  resize  the  ruler 


fDisableSelection 


fDrawInactiveSelection 

bit  19 


Reserved 


bit  20         Controls  whether  user  can  select  text: 
1  -  User  cannot  select  text 

0  -  User  can  select  text 

Controls  how  inactive  selected  text  is  displayed: 

1  -  TextEdit  draws  a  box  around  inactive  selections 
0  -  TextEdit  does  not  display  inactive  selections 

bits  0-18     Must  be  set  to  0 
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indentRect        Each  coordinate  of  this  rectangle  specifies  the  amount  of  white  space 
to  leave  between  the  boundary  rectangle  for  the  control  and  the  text 
itself,  in  pixels.  Default  values  are  (2,6,2,4)  in  640  mode  and  (2,4,2,2) 
in  320  mode.  Each  indentation  coordinate  may  be  specified 
individually.  In  order  to  assert  the  default  for  any  coordinate,  specify 
its  value  as  $FFFF. 

vertBar  Handle  of  the  vertical  scroll  bar  to  use  for  the  TextEdit  window.  If  you 

do  not  want  a  scroll  bar  at  all,  then  set  this  field  to  NIL.  If  you  want 
TextEdit  to  create  a  scroll  bar  for  you,  just  inside  the  right  edge  of  the 
boundary  rectangle  for  the  control,  then  set  this  field  to  $FFFFFFFF. 

vert  Amount  Specifies  the  number  of  pixels  to  scroll  whenever  the  user  presses  the 
up  or  down  arrow  on  the  vertical  scroll  bar.  In  order  to  use  the  default 
value  (9  pixels),  set  this  field  to  $0000. 

horzBar  Must  be  set  to  NIL. 

horzAmount  Must  be  set  to  0. 

styieRef  Reference  to  initial  style  information  for  the  text.  See  the  description 

of  the  TEFormat  record  in  Chapter  49,  "TextEdit,"  for  information 
about  the  format  and  content  of  a  style  descriptor.  Bits  1  and  0  of 
moreFiags  define  the  type  of  reference  (pointer,  handle,  resource 
ID).  To  use  the  default  style  and  ruler  information,  set  this  field  to 
NULL. 


textDescriptor 

Input  text  descriptor  that  defines  the  reference  type  for  the  initial 

text  (which  is  in  text  Re  f )  and  the  format  of  that  text.  See 

Chapter  49,  "TextEdit,"  for  detailed  information  on  text  and 

reference  formats. 

textRef  Reference  to  initial  text  for  the  edit  window.  If  you  are  not  supplying 

any  initial  text,  then  set  this  field  to  NULL. 

textLength        If  textRef  is  a  pointer  to  the  initial  text,  then  this  field  must  contain 
the  length  of  the  initial  text.  For  other  reference  types,  TextEdit 
extracts  the  length  from  the  reference  itself. 

♦    Note:  YOU  must  specify  or  omit  the  textDescriptor,  textRef,  and  textLength 
fields  as  a  group. 
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maxChars 


maxLines 


Maximum  number  of  characters  allowed  in  the  text.  If  you  do  not  want 
to  define  any  limit  to  the  number  of  characters,  then  set  this  field  to 
NULL. 

Must  be  set  to  0. 


maxCharsPerLines 

Must  be  set  to  NULL. 

maxHeight  Must  be  set  to  0. 

coiorRef  Reference  to  the  color  table  for  the  text.  This  is  a  Text  Edit  color  table 

(see  Chapter  49,  "TextEdit,"  for  format  and  content  of 
TECoiorTabie).  Bits  2  and  3  of  moreFiags  define  the  type  of 
reference  stored  here. 

drawMode  This  is  the  text  mode  used  by  QuickDraw  II  for  drawing  text.  See 

Chapter  16,  "QuickDraw  II,"  in  Volume  2  of  the  Toolbox  Reference  for 
details  on  valid  text  modes. 

filterProcPtr  Pointer  to  a  filter  routine  for  the  control.  See  Chapter  49,  "TextEdit," 
for  details  on  TextEdit  generic  filter  routines.  If  you  do  not  want  to 
use  a  filter  routine  for  the  control,  set  this  field  to  NIL. 
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rCHnputString         $8005 

Figure  E-17  defines  the  layout  of  resource  type  rci  input  string  ($8005).  Resources  of 
this  type  contain  GS/OS  Class  1  input  strings  (length  word  followed  by  data). 


Figure  E-17     GS/OS  classl  input  string,  type  rci  input  st  ring  ($8005) 


$00 
$02 


length 


Word 


stringCharacters       '■    length  Bytes 


length  Indicates  the  number  of  bytes  stored  at  stringCharacters.  This  is 

an  unsigned  integer;  valid  values  lie  in  the  range  from  1  to  65535. 

stringCharacters 

Array  of  length  characters. 
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rClOutputString  $8023 

Figure  E-18  defines  the  layout  of  resource  type  rcioutputstring  ($8023).  Resources 
of  this  type  contain  GS/OS  class  1  output  strings  (buffer  size  word  and  string  length  word 
followed  by  data). 


Figure  E-18     GS/OS  classl  output  string,  type  rci  output  string  ($8023) 


$00 

$02 
$04 


—  bufferSize  — 


—        stringLength        — 


Word 
Word 


stringCharacters      :    String   LengthBytes 


bufferSize        Indicates  the  number  of  bytes  in  the  entire  structure,  including 
bufferSize. 

stringLength     Indicates  the  number  of  bytes  Stored  at  stringCharacters.  This  is 
an  unsigned  integer;  valid  values  lie  in  the  range  from  1  to  65535.  If  the 
returned  string  will  not  fit  in  the  buffer,  this  field  indicates  the  length 
of  the  string  the  system  wants  to  return.  Your  program  should  add  four 
to  that  value  (tO  account  for  bufferSize  and  stringLength, 

resize  the  buffer,  and  reissue  the  call). 

stringCharacters 

Array  of  stringLength  characters. 
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rCString         $801D 

Figure  E-19  defines  the  layout  of  resource  type  rCString  ($801D).  Resources  of  this 
type  contain  C  strings  (null-terminated  character  array). 


Figure  E-19     C  string,  type  rest  ring  ($801D) 


$00 1  | 

•       stringCharaoters       '■   Bytes 


stringCharacters 

Array  of  characters;  last  character  must  be  a  null  ($00).  The  string  may 
contain  up  to  65,535  characters,  including  the  null  terminator. 
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rlcon     $8001 


Figure  E-20  defines  the  layout  of  resource  type  ricon  ($8001). 


Figure  fr-20     Icon,  type  neon  ($8001) 


$00 

—     iconType     - 

Word 

$02 

—     iconSize     — 

Word 

$04 

—     iconHeight     — 

Word 

$06 

—     iconWidth     — 

Word 

$08 

iconlmage 

Array 

$xx 

iconMask 

Array 

iconType  Contains  flags  defining  the  type  of  icon  stored  in  the  icon  record. 

Color  Indicator  Bit  15         Indicates  whether  the  icon  contains  a  color  or 

black-and-white  image 
1  -  Icon  is  color 
0  -  Icon  is  black  and  white 

iconsize  Specifies  the  size  of  the  icon  image  stored  at  iconlmage,  in  bytes. 

iconHeight  Specifies  the  height  of  the  icon,  in  pixels. 

iconwidth  Specifies  the  width  of  the  icon,  in  pixels. 

iconlmage  Contains  iconsize  bytes  of  icon  image  data. 

iconMask  Contains  iconsize  bytes  of  mask  data  to  be  applied  to  the  image 

located  at  iconlmage. 
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rKTransTable         $8021 

Figure  E-21  defines  the  layout  of  resource  type  rKTransTable  ($8021).  Resources  of 
this  type  define  keystroke  translation  tables  for  use  by  the  Event  Manager  (see 
Chapter  31,  "Event  Manager  Update,"  earlier  in  this  book  for  complete  information  on  the 
format  and  content  of  resources  of  this  type). 


Figure  E-21     Keystroke  translation  table,  type  rKTransTable  ($8021) 


$ooo  I  | 

'■         transTabie  '■  256  Bytes— Keystroke  translation  array 


$100 

:  deadKeyTabie        '■  xx  Bytes— Dead-key  validation  array 

$100+xx  I 

'■  repiacementTabie     '■  yy  Bytes— Dead-key  replacement  array 


transTabie        This  is  a  packed  array  of  bytes  used  to  map  the  ASCII  codes  produced 
by  the  keyboard  into  the  character  value  to  be  generated.  Each  cell  in 
the  array  directly  corresponds  to  the  ASCII  code  that  is  equivalent  to 
the  cell  offset.  For  example,  the  transTabie  cell  at  offset  $0D  (13 
decimal)  contains  the  character  replacement  value  for  keyboard  code 
$0D,  which,  for  a  straight  ASCII  translation  table,  is  a  Return  character 
(CR).  The  transTabie  cells  from  128  to  255  ($80  to  $FF)  contain 
values  for  Option-key  sequences  (such  as  Option-S). 
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deadKeyTable 


This  table  contains  entries  used  to  validate  dead  keys.  Dead  key 
refers  to  keystrokes  used  to  introduce  multikey  sequences  that  result 
in  single  characters.  For  example,  pressing  Option-u  followed  by  e 
yields  an  e  with  an  umlaut.  There  is  one  entry  in  deadKeyTable  for 
each  defined  dead  key.  The  last  entry.must  be  set  to  $0000.  Each  entry 
must  be  formatted  as  follows: 


deadKey 


offset 


Byte— Character  code  for  dead  key 

Byte— Offset  from  deadKeyTable  into  replacement  Table 


deadKey  Contains  the  character  code  for  the  dead  key.  The  system  uses 

this  value  to  check  for  user  input  of  a  dead  key.  The  system 
compares  this  value  with  the  first  user  keystroke. 

offset  Byte  offset  from  beginning  of  deadKeyTable  into  relevant 

subarray  in  repiacementTabie,  divided  by  2.  The  system 
uses  this  value  to  access  the  valid  replacement  values  for  the 
dead  key  in  question. 

repiacementTabie 

This  table  contains  the  valid  replacement  values  for  each  dead  key 
combination.  This  table  is  made  up  of  a  series  of  variable-length 
subarrays,  each  relevant  to  a  particular  dead  key.  The  last  entry  in  each 
sub-array  must  be  set  to  $0000.  Each  entry  in  the 
repiacementTabie  must  be  formatted  as  follows: 


deadKey 


offset 


Byte— Character  code  for  dead  key 

Byte— Offset  from  deadKeyTable  into  repiacementTabie 


scanKey 


replaceValue 


Contains  a  valid  character  code  for  dead  key  replacement.  The 
system  uses  this  field  to  determine  whether  the  user  entered  a 
valid  dead  key  combination.  The  system  compares  this  value 
with  the  second  user  keystroke. 

Contains  the  replacement  value  for  the  character  specified  in 
scanKey  for  this  entry.  The  system  delivers  this  value  as  the 
replacement  for  a  valid  dead  key  combination. 
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rListRef 


$801C 


Figure  E-22  defines  the  layout  of  the  array  element  that  comprises  resource  type 
rListRef  ($801C).  Resources  of  this  type  define  members  of  list  controls  (see 
Chapter  28,  "Control  Manager  Update,"  earlier  in  this  book  for  more  information  on  list 
controls).  A  single  rListRef  resource  may  contain  more  than  one  of  these  elements;  you 
concatenate  the  elements  to  form  the  resource. 


Figure  E-22     List  member  reference  array  element,  type  rListRef  ($801C) 


$04 
$05 


item 


-   Long— Pointer  to  list  string 


Byte— Control  flags  for  list  member 

Array— List  member  data;  (listMemSize  -  5  )  bytes  of  data 


J 


itemPtr 

itemFlag 

memSelect 


Reserved 

item 


Pointer  to  the  list  member  string. 
Control  flags  for  the  member. 

Bits  6-7      Indicates  whether  the  item  is  selected 

00  -  Item  is  enabled  but  not  selected 

01  -  Item  is  disabled  (cannot  be  selected) 

10  -  Item  is  selected 

11  -  Invalid  value 
Bits  0-5      Must  be  set  to  0 

Application-specific  data  for  the  list  member.  The  listMemSize 
field  of  the  list  control  template  specifies  the  size  of  this  field,  plus  5. 
For  example,  in  order  to  assign  a  two-byte  tag  to  each  list  member, 
you  would  set  listMemSize  to  7  (5+2)  and  place  the  tag  value  at 
item  in  each  list  member. 
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rMenu         $8009 

Figure  E-23  defines  the  layout  of  resource  type  rMenu  ($8009).  Resources  of  this  type 

define  parameters  to  some  new  Menu  Manager  tool  calls.  See 

Chapter  37,  "Menu  Manager  Update,"  earlier  in  this  book  for  more  information. 


Figure  E^-23     Menu  template,  type  rMenu  ($8009) 


$00 

—            version 

Word— Version  number  for  template;  must  be  set  to  0 

$02 

—              menu ID 

Word— Menu  ID 

$04 

—           menuFlag 

Word— Menu  flag  word 

$06 

—       menuTltleRef 

_ 

Long— Reference  to  menu  title  string 

$0A 

itemRefArray 

n  Longs— References  to  menu  items 

version 


menuID 


Identifies  the  version  of  the  menu  template.  The  Menu  Manager  uses 
this  field  to  distinguish  between  different  revisions  of  the  template. 
Must  be  set  to  0. 

Unique  identifier  for  the  menu.  See  Chapter  13,  "Menu  Manager,"  in  the 
Toolbox  Reference for  information  on  valid  values  for  menu  id. 
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menuFlag  Bit  flags  controlling  the  display  and  processing  attributes  of  the  menu. 

Valid  values  for  menuFlag  are: 

titieRef  Type  bits  14-15   Defines  the  type  of  reference  in  menuTitieRef : 

00  -  Reference  is  pointer 

01  -  Reference  is  handle 

10  -  Reference  is  resource  ID 

11  -  Invalid  value 
bits  12-13   Defines  the  type  of  reference  in  each  entry  of 

itemRef  Array  (all  array  entries  must  be  of  the  same 
type): 

00  -  References  are  pointers 

01  -  References  are  handles 

10  -  References  are  resource  IDs 

11  -  Invalid  value 
Must  be  set  to  0 


itemRef Type 


Reserved  bits  9-11 

alwaysCallmChoose 

bit  8 


disabled 


Reserved 

XOR 


custom 


allowCache 


Reserved 


menuTitieRef 


bit  7 


bit  6 
bit  5 


bit  4 


bit  3 


bits  0-2 


Causes  the  Menu  Manager  to  call  a  custom  menu 
defProc  mChoose  routine  even  when  the  mouse  is  not 
in  the  menu  rectangle  (supported  tear-off  menus): 

0  -  Do  not  always  call  mChoose  routine 

1  -  Always  call  mChoose  routine 
Enables  or  disables  the  menu: 

0  -  Menu  enabled 

1  -  Menu  disabled 
Must  be  set  to  0 

Controls  how  selection  highlighting  is  performed: 

0  -  Do  not  use  XOR  to  highlight 

1  -  Use  XOR  to  highlight  item 

Indicates  whether  custom  or  standard  menu: 

0  -  Standard  menu 

1  -  Custom  menu 
Controls  menu  caching: 

0  -  Do  not  cache  menu 

1  -  Menu  caching  allowed 
Must  be  set  to  0 


Reference  to  title  string  for  menu.  The  titieRef  Type  bits  in 
menuFlag  indicate  whether  menuTitieRef  contains  a  pointer,  a 
handle,  or  a  resource  ID.  If  menuTitieRef  is  a  pointer,  then  the  title 
string  must  be  a  Pascal  string.  Otherwise,  the  Menu  Manager  can 
retrieve  the  string  length  from  control  information  in  the  handle. 
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itemRef  Array    Array  of  references  to  the  menu  items  for  the  menu.  The 

itemRef  Type  bits  in  menuFlag  indicate  whether  the  entries  in  the 
array  are  pointers,  handles,  or  resource  IDs.  Note  that  all  array  entries 
must  contain  the  same  reference  type.  The  last  entry  in  the  array  must 
be  set  to  $00000000. 
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rMenuBar 


$8008 


Figure  E-24  defines  the  layout  of  resource  type  rMenuBar  ($8008).  Resources  of  this  type 
define  the  characteristics  of  a  menu  bar  for  new  Menu  Manager  tool  calls.  For  more 
information,  see  Chapter  37,  "Menu  Manager  Update,"  earlier  in  this  book. 


Figure  E-24     Menu  bar  record,  type  rMenuBar  ($8008) 


$00 
$02 
$04 


—  version 


menuFlag  — 


Word— Version  number  for  template;  must  be  set  to  0 
Word— Menu  bar  flag  word 


I 


menuRef  Array         j  n  Longs — References  to  menus 


version 

menuBarFlag 
menuRefType 


Reserved 


menuRef Array 


Identifies  the  version  of  the  menu  bar  template.  The  Menu  Manager 
uses  this  field  to  distinguish  between  different  revisions  of  the 
template.  Must  be  set  to  0. 

Bit  flags  controlling  the  display  and  processing  attributes  of  the  menu 
bar.  Valid  values  for  menuBarFlag  are: 

bits  14-15   Defines  the  type  of  reference  in  each  entry  of 

menuRef  Array  (all  array  entries  must  be  of  the  same 
type): 

00  -  References  are  pointers 

01  -  References  are  handles 

10  -  References  are  resource  IDs 

11  -  Invalid  value 
bits  0-13     Must  be  set  to  0 

Array  of  references  to  the  menus  for  the  menu  bar.  The  menuRefType 
bits  in  menuBarFlag  indicate  whether  the  entries  in  the  array  are 
pointers,  handles,  or  resource  IDs.  Note  that  all  array  entries  must 
contain  the  same  reference  type.  The  last  entry  in  the  array  must  be  set 
to  $00000000. 
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rMenuitem 


$800A 


Figure  E-25  defines  the  layout  of  resource  type  rMenuitem  ($800A).  Resources  of  this 

type  define  menu  items  to  some  new  Menu  Manager  tool  calls.  See 

Chapter  37,  "Menu  Manager  Update,"  earlier  in  this  book  for  more  information. 


Figure  E-25     Menu  item  template,  type  rMenuitem  ($800A) 


$00 

$02 

$04 
$05 
$06 

$08 
$0A 


version 


itemID 


itemChar 


itemAltChar 


—  itemCheck  — 


Word— Version  number  for  template;  must  be  set  to  0 

Word— Menu  item  ID 

Byte— Primary  keystroke  equivalent  character 
Byte— Alternate  keystroke  equivalent  character 

Word— Character  code  for  checked  items 


ltemFiag         -   Word— Menu  item  flag  word 


itemTitieRef      -   Long — Reference  to  item  title  string 


version 


itemID 


Identifies  the  version  of  the  menu  item  template.  The  Menu  Manager 
uses  this  field  to  distinguish  between  different  revisions  of  the  menu 
item  template.  Must  be  set  to  0. 

Unique  identifier  for  the  menu  item.  See  Chapter  13,  "Menu  Manager," 
in  the  Toolbox  Reference  for  information  on  valid  values  for  itemiD. 


itemChar,  itemAltChar 

These  fields  define  the  keystroke  equivalents  for  the  menu  item.  The 
user  can  select  the  menu  item  by  pressing  the  Command  key  along  with 
the  key  corresponding  to  one  of  these  fields.  Typically,  these  fields 
contain  the  upper  and  lower  case  ASCII  codes  for  a  particular 
character.  If  you  only  have  a  single  key  equivalence,  set  both  fields 
with  that  value. 

itemCheck  Defines  the  character  to  be  displayed  next  to  the  item  when  it  is 

checked. 
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itemFlag 


titleRefType 


Reserved 

bit  13 

shadow 

bit  12 

outline 

bit  11 

Reserved 

bits  8-10 

disabled 

bit  7 

divider 

bit  6 

XOR 

bit  5 

Reserved 

bits  3-4 

underline 

bit  2 

italic 

bitl 

bold 


itemTitleRef 


Bit  flags  controlling  the  display  attributes  of  the  menu  item.  Valid 
values  for  itemFlag  are: 

bits  14-15   Defines  the  type  of  reference  in  itemTitleRef: 

00  -  Reference  is  pointer 

01  -  Reference  is  handle 

10  -  Reference  is  resource  ID 
11 -Invalid  value 
Must  be  set  to  0 
Indicates  item  shadowing: 

0  -  No  shadow 

1  -  Shadow 
Indicates  item  oudining 

0  -  Not  outlined 

1  -  Outlined 
Must  be  set  to  0 
Enables  or  disables  the  menu  item: 

0  -  Item  enabled 

1  -  Item  disabled 
Controls  drawing  divider  below  item: 

0  -  No  divider  bar 

1  -  Divider  bar 
Controls  how  highlighting  is  performed: 

0  -  Do  not  use  XOR  to  highlight 

1  -  Use  XOR  to  highlight  item 
Must  be  set  to  0 
Controls  item  underlining: 

0  -  Do  not  underline  item 

1  -  Underline  item 
Indicates  whether  item  is  italicized 

0  -  Not  italicized 

1  -  Italicized 

bit  0  Indicates  whether  item  is  drawn  bold: 

0  -  Not  bold 
1-Bold 

Reference  to  tide  string  for  menu  item.  The  titleRefType  bits  in 
itemFlag  indicate  whether  itemTitleRef  contains  a  pointer,  a 
handle,  or  a  resource  ID.  If  itemTitleRef  is  a  pointer,  then  the  title 
string  must  be  a  Pascal  string.  Otherwise,  the  Menu  Manager  can 
retrieve  the  string  length  from  control  information  in  the  handle. 
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rPString         $8006 

Figure  E-26  defines  the  layout  of  resource  type  rP string  ($8006).  Resources  of  this  type 
contain  Pascal  strings. 


Figure  E-26     Pascal  string,  type  rP  string  ($8006) 


$00 
$01 


lengthByte 


Byte 


stringCharacters       :   nByteS 

i 


lengthByte        Number  of  bytes  of  data  stored  in  stringCharacters  array. 

stringCharacters 

Array  of  lengthByte  characters. 
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rResName 


$8014 


Figure  E-27  defines  the  layout  of  resource  type  rResName  ($8014).  Resources  of  this  type 
define  name  strings  for  resources  of  a  given  type  and  ID.  The  resource  ID  value  assigned  to 
an  rResName  resource  must  be  formed  as  follows: 

$0001  xxxx         where  xxxx  corresponds  to  the  resource  type  for  resources  whose  names 
are  defined  in  this  resource 

Within  the  rResName  resource  you  define  name  strings  corresponding  to  resources  with 
specified  resource  IDs.  Names  are  stored  in  Pascal  strings,  and  must  be  unique  within  the 
appropriate  resource  type.  Resource  names  are  not  required,  so  you  may  specify  names 
for  only  a  few  resources  within  a  given  type. 


Figure  E-27     Resource  name  array,  type  rResName  ($8014) 


$00 
$02 

$06 


versNum  —    Word 


—  nameCount 


Long 


resNames 


:  Array  of  nameCount  Name  blocks 
J 


versNum  Specifies  the  resource  template  version.  Must  be  set  to  1. 

nameCount  Count  of  entries  in  the  resNames  name  definition  array. 
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resNames  Array  of  name  strings.  Each  entry  must  be  formatted  as  follows: 


$00 


$04 


—    namedResID    - 


Long 


resName  '■    Pascal  String 


namedResID        ID  of  the  resource  for  this  name. 
resName  Name  string  for  the  resource. 
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rStringList  $8007 

Figure  E-28  defines  the  layout  of  resource  type  rStringList  ($8007).  Resources  of  this 
type  contain  an  array  of  Pascal  strings. 


Figure  E-28     Pascal  string  array,  type  rStringList  ($8007) 


$00 
$02 


count  —   Word 

strings  j  Array  of  Pascal  strings  (resourcesof  type  rPString ) 


count  Indicates  the  number  of  Pascal  strings  stored  at  st ri ngs . 

strings  An  array  of  count  Pascal  strings. 
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next         $8016 

Figure  E-29  defines  the  layout  of  resource  type  rText  ($8016).  Resources  of  this  type 
contain  text  blocks  (data  arrays  with  no  embedded  length  information;  block  length  must 
be  indicated  in  other  fields). 


Figure  E-29     Text  block,  type  next  ($8016) 


$00 1  ] 

•       stringCharacters       ■    Bytes 


stringCharacters 

Array  of  up  to  65,535  characters.  Any  length  information  is  contained 

in  a  separately  maintained  field. 
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rTextBlock         $8011 


Figure  E-30  defines  the  layout  of  resource  type  rTextBlock  ($8011).  Resources  of  this 
type  contain  text  blocks  (data  arrays  with  no  embedded  length  information;  block  length 
must  be  indicated  in  other  fields). 


Figure  E-30     Text  block,  type  rTextBlock  ($8011) 


$00  r 


stringCharacters      •   Bytes 


stringCharacters 

Array  of  up  to  65535  characters.  Any  length  information  is  contained  in 
a  separately  maintained  field. 
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rTextBox2         $800B 

Figure  E-31  defines  the  layout  of  resource  type  rTextBox2  ($800B).  Resources  of  this 
type  contain  data  formatted  as  input  to  the  LETextBox2  LineEdit  tool  call  (see 
Chapter  10,  "LineEdit  Tool  Set,"  in  the  Toolbox  Reference  for  details). 


Figure  E-31     LETextBox2  input  text,  type  rTextBox2  ($800B) 


$00 
$02 


length 


Word 


stringCharacters       •   Bytes 


length  Indicates  the  number  of  bytes  stored  at  stringCharacters.  Valid 

values  lie  in  the  range  from  1  to  32767. 

stringCharacters 

Array  of  up  to  32767  characters.  Formatting  information  is  embedded 

in  the  character  array,  and  is  included  in  the  value  of  length.  See 

Chapter  10,  "LineEdit  Tool  Set,"  in  the  Toolbox  Reference  for  complete 

information  on  the  syntax  for  this  embedded  appearance 

information. 
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rToolStartup 


$8013 


Figure  E-32  defines  the  layout  of  resource  type  rTool startup  ($8013).  Resources  of 
this  type  define  tool  set  start  up  records  for  use  with  the  Tool  Locator  startupToois 
and  shutDownToois  tool  calls.(see  Chapter  51,  Tool  Locator  Update,"  earlier  in  this 
book  for  more  information). 


Figure  E-32     Tool  start  stop  record,  type  rToolStartup  ($8013) 

Word— Flag  word— must  be  set  to  0 
Word— Video  mode  for  QuickDraw  II 
Word— Set  by  StartUpTools 

Long— Set  by  StartUpTools 
J  Word— Number  of  entries  in  toolArray 
tooiArray  :  numTool s ToolSpec  records 


$00 

- 

flags 

- 

$02 

- 

videoMode 

- 

$04 

- 

resFilelD 

- 

$06 

dPageHandle 

— 

$0A 

numTools 

- 

$0C 

videoMode 


resFilelD 


dPageHandle 


Defines  the  video  mode  for  QuickDraw  II.  See 

Chapter  16,  "QuickDraw  II,"  in  the  Toolbox  Reference  for  valid  values. 

The  StartUpTools  call  sets  this  field.  ShutDownToois  requires  it 
as  input. 

The  StartUpTools  call  sets  this  field.  ShutDownToois  requires  it 
as  input. 
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tooiArray  Each  entry  defines  a  tool  set  to  be  started.  The  numToois  field 

specifies  the  number  of  entries  in  this  array.  Each  entry  is  formatted  as 
follows: 


$00 
$02 


—     toolNumber     — 


—    minVersion 


Word— Tool  set  identifier 

Word— Minimum  acceptable  tool  set  version 


toolNumber 


toolVersion 


Specifies  the  tool  set  to  be  loaded  Valid  tools  set  numbers  are 
discussed  in  Chapter  51,  "Tool  Locator  Update,"  earlier  in  this 
book. 

Specifies  the  minimum  acceptable  version  for  the  tool  set.  See 
Chapter  24,  "Tool  Locator,"  in  the  Toolbox  Reference  for  the 
format  of  this  field. 
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rTwoRects         $801A 


Figure  E-33  defines  the  layout  of  resource  type  rTwoRects  ($801A). 


Figure  E-33     Two  rectangles,  type  rTwoRects  ($801  A) 


$00 


$08 


recti  :    Rectangle 


rect2  :    Rectangle 


recti 
rect2 


First  rectangle. 
Second  rectangle. 
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rWindColor 


$8010 


Figure  E-34  defines  the  layout  of  resource  type  rwindcoior  ($8010).  Resources  of  this 
type  define  window  color  tables  for  the  Window  Manager. 


Figure  E-34     Window  color  table,  type  rwindcoior  ($8010) 


$00 

—           frameColor 

Word 

$02 

-          titleColor 

Word 

$04 

—            tBarColor 

Word 

$06 

—            growColor 

Word 

$08 

—            InfoColor 

Word 

frameColor        Color  of  the  window  frame  and  of  the  alert  frame. 


Reserved 
windowFrame 

Reserved 
titleColor 

Reserved 

inactiveTitleBar  bits  8-11 
bits  4-7 
bits  0-3 


bits  8-15     Must  be  set  to  0 

bits  4-7      Color  of  window  frame— value  is  an  index  into  the 

active  color  table 
bits  0-3       Must  be  set  to  0 

Colors  of  inactive  title  bar,  inactive  title,  and  active  title: 


inactiveTitle 


activeTitle 


tBarColor 


bits  12-15   Must  be  set  to  0 

Color  of  inactive  title  bars— value  is  an  index  into  the 
active  color  table 

Color  of  inactive  titles — value  is  an  index  into  the 
active  color  table 

Color  of  active  titles,  close  box,  and  zoom  box- 
value  is  an  index  into  the  active  color  table. 


Color  and  pattern  information  for  active  title  bar: 


pattern 

bits  8-15 

Defines  pattern  for  title  bar: 
$00  -  Solid 
$01  -  Dither 
$02 -Lined 

patternColor 

bits  4-7 

Color  for  pattern— value  is  an  index  into  the  active 
color  table 

backColor 

bits  0-3 

Background  color— value  is  an  index  into  the  active 
color  table. 
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growcoior  Color  of  size  box  and  alert  frame's  middle  outline: 

alertMidFrame        bits  12-15   Color  of  alert  frame  middle  outline— value  is  an  index 

into  the  active  color  table 
Reserved  bits  8-11     Must  be  set  to  0 

sizeunseiected      bits  4-7      Color  for  unselected  size  box— value  is  an  index  into 

the  active  color  table 
sizeseiected  bits  0-3      Color  for  selected  size  box— value  is  an  index  into  the 

active  color  table. 

InfoColor  Color  of  information  bar  and  alert  frame's  inside  outline: 

alertMidFrame        bits  12-15   Color  of  alert  frame  inside  outline— value  is  an  index 

into  the  active  color  table 

Reserved  bits  8-11     Must  be  set  to  0 

inf  oBar  bits  4-7      Color  for  information  bar— value  is  an  index  into  the 

active  color  table 

Reserved  bits  0-3      Must  be  set  to  0 
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rWindParaml 


$800E 


Figure  E-35  defines  the  layout  of  resource  type  rWindParaml  ($800E).  This  resource 
defines  a  template  used  to  create  windows  with  the  Newwindow2  Window  Manager  tool 
call  (see  Chapter  52,  "Window  Manager  Update,"  earlier  in  this  book).  Most  of  these  fields 
correspond  to  fields  in  the  Newwindow  parameter  list  (defined  in  the  Toolbox  Reference). 


■    Figure  E-35     Window  template,  type  rWindParaml  ($800E) 
$00 

$02 
$04 


—  plLength 


$08 


$0C 


pi Frame 


plTitle 


plRefCon 


Word 


Word— See  NewWindow  wFrameBits  parameter 
Long 


plZoomRect 

$14 

_ 

plColorTable 

— ■ 

$18 

- 

plYOrigin 

- 

$1A 

plXOrigin 

- 

$1C 

plDataHeight 

- 

$1E 

plDataWidth 

- 

$20 

plMaxHeight 

- 

$22 

plMaxWidth 

- 

$24 

plVerScroll 

- 

$26 

plHorScroll 

- 

$28 

plVerPage 

- 

$2A 

plHorPage 

- 

continued 

Long— See  NewWindow  tvRefCon  parameter 
\  Rectangle— See  NewWindow  wZoom parameter 

Long 

Word— See  NewWindow  wYOrigin  parameter 
Word— See  NewWindow  wXOriginpznmeter 
Word— See  NewWindow  wDataH parameter 
Word— See  NewWindow  wDataW  parameter 
Word— See  NewWindow  iwMotf/parameter 
Word— See  NewWindow  wMaxW  parameter 
Word— See  NewWindow  wScrollVer  parameter 
Word— See  NewWindow  wScroUHor  parameter 
Word--See  NewWindow  wPageVer  parameter 
Word— See  NewWindow  wPageHor  parameter 


E-68      Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  11GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


$2C  _ 

—    plInfoText 


$30 
$32 

$36 

$3A 

$3E 
U6 

$4A 

$4E 


continued 


plInfoHeight         - 


plDefProc 


—  plInfoDraw 


Long— See  NewWindow  wlnfoRefCon  parameter 
Word— See  NewWindow  wlnfoHeight  parameter 
Long— See  NewWindow  wFrameDefProc parameter 


Long— See  NewWindow  wlnfoDefProc  parameter 

picontentoraw     -j  Long— See  NewWind_ow  ivContDefProc  parameter 
piposition  \  Rectangle— See  NewWindow  wPosition  parameter 

Long— See  NewWindow  wPlane  parameter 


plPlane 


—       plControlList       — 


plInDesc  -    Word 


Long 


pi  Length  Specifies  the  number  of  bytes  in  the  template,  including  the  length  of 

piLength.  Must  be  set  to  $50. 

piTitie  Reference  to  title  string  for  the  window.  The  contents  of  pi inDesc 

specify  the  type  of  reference  stored  here.  The  tide  must  be  stored  in  a 
Pascal  string,  containing  both  a  leading  and  a  trailing  space. 

If  pi  Title  is  set  to  NIL,  the  Window  Manager  will  create  a  window 
without  a  tide  bar.  If  your  program  is  creating  a  window  with  a  title 
bar,  you  must  specify  a  title  of  some  sort.  In  order  to  create  a  window 
without  a  tide,  make  piTitie  (or  titlePtr on  the  Newwindow2  call) 
refer  to  a  null  string. 

Note  that  the  Window  Manager  creates  a  copy  of  the  tide  string,  so 
that  your  program  can  free  the  memory  for  this  string  after  issuing  the 
NewWindow2  call. 

If  you  specify  a  non-NIL  value  for  titlePtr  on  the  Newwindow2  call, 
this  field  is  ignored. 
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piCoiorTabie    Reference  to  the  color  table  for  the  window.  The  contents  of 
piinDesc  specify  the  type  of  reference  stored  here.  If 
piCoiorTabie  is  set  to  NIL,  the  Window  Manager  assumes  that 
there  is  no  color  table  for  the  window. 

The  format  of  the  color  table  is  defined  in 
Chapter  25,  "Window  Manager,"  in  the  Toolbox  Reference.  If 
piCoiorTabie  refers  to  a  resource,  then  the  color  table  must  be 
defined  in  a  resource  of  type  rwindcoior . 

picontroiList  Reference  to  the  template  or  templates  defining  controls  for  the 

window.  The  Window  Manager  passes  this  value  to  the  NewControi2 
Control  Manager  tool  call  as  the  reference  parameter.  Note  that 
piinDesc  contains  the  data  for  the  NewControi2  referenceDesc 
parameter.  Refer  to  Chapter  28,  "Control  Manager  Update,"  in  this 
book  for  more  information  about  NewCont  roi2. 

If  this  field  is  set  to  NIL,  then  the  Window  Manager  assumes  that  there 
is  no  control  list  for  the  window  and  does  not  call  NewCont  r oi  2 . 

piinDesc  Defines  the  type  of  reference  stored  in  piCoiorTabie  and 

piTitie.  Also  contains  the  referenceDesc  value  for  NewControi2 
that  defines  the  contents  of  picontroiList: 


Reserved 

colorTableRef 


titleRef 


controlRef 


bits  12-15   Must  be  set  to  0 
bits  10-11    Define  the  type  of  reference  stored  in 
piCoiorTabie: 

00  -  Reference  is  pointer  to  color  table 

01  -  Reference  is  handle  to  color  table 

10  -  Reference  is  resource  ID  of  rwindcoior 
resource 
11 -Invalid  value 
bits  8-9      Define  the  type  of  reference  stored  inpiTitie: 

00  -  Reference  is  pointer  to  Pascal  string 

01  -  Reference  is  handle  to  Pascal  string 

10  -  Reference  is  resource  ID  of  rP string  resource 
11 -Invalid  value 
bits  0-7      Define  the  type  of  reference  stored  in 

picontroiList.  Passed  direcdy  to  the 
NewCont  roi  2  Control  Manager  tool  call  as  the 
referenceDesc  parameter.  For  valid  values,  see  the 
description  of  the  NewControi2  tool  call  in 
Chapter  28,  "Control  Manager  Update,"  earlier  in  this 
book. 
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rWindParam2         $800F 

Figure  E-36  defines  the  layout  of  resource  type  rwindParam2  ($800F).  This  resource 
defines  a  template  used  to  create  windows  with  the  Newwindow2  Window  Manager  tool 
call  (see  Chapter  52,  "Window  Manager  Update,"  earlier  in  this  book).  Use  this  template 
for  custom  windows. 


Figure  E-36     Window  template,  type  rwindParam2  ($800F) 


p2Data  \  Byte  array 


p2ListiD  Specifies  the  resource  template  version.  Must  be  set  to  NIL. 

p2DefProc  Pointer  to  the  definition  procedure  for  the  window.  When  using  the 

rwindParam2  window  template,  you  must  pass  a  pointer  to  a  valid 
definition  procedure,  either  in  the  template  or  with  the  defProcPtr 
parameter  to  the  Newwindow2  Window  Manager  tool  call.  On  disk, 
this  field  does  not  contain  a  valid  value. 

p2Data  Window  definition  data  required  by  the  routine  pointed  to  by 

p2Def  Proc.  The  format  and  content  of  this  field  is  determined  by 
the  window  definition  procedure. 
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Appendix  F   Delta  Guide 


This  appendix  collects  all  information  that  corrects  errors  or  clarifies 
ambiguities  in  Volumes  1  and  2  of  the  Toolbox  Reference.  This 
information  was  derived  from  the  "Error  corrections"  and  "Clarifications" 
sections  of  each  chapter  in  this  book.  This  appendix  contains  a  separate 
major  section  for  tool  set  to  be  addressed;  the  sections  are  presented 
alphabetically,  by  tool  set  name. 
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Apple  Desktop  Bus 

The  following  sections  correct  errors  or  omissions  in 

Chapter  3,  "Apple  Desktop  Bus  Tool  Set,"  in  Volume  1  of  the  Toolbox  Reference. 


Error  correction 

The  parameter  table  for  the  ReadKeyMicroData  tool  call  ($0A09)  in  Volume  1  of  the 
Toolbox  Reference  incorrectly  describes  the  format  for  the  readconf  ig  command  ($0B). 
The  description  should  be  as  follows. 


Command 


dataLength 


Name 


Action 


$0B  3  readconf  ig    Read  configuration;  dataPtr  refers  to  a 

3-byte  data  structure: 
Byte     ADB  keyboard  and  mouse 
addresses 

low  nibble  -  keyboard 
high  nibble  -  mouse 
Byte     Keyboard  layout  and  display 
language 

low  nibble  -  keyboard  layout 
high  nibble  -  display  language 
Byte     Repeat  rate  and  delay 
low  nibble  -  repeat  rate 
high  nibble  -  repeat  delay 

The  description  of  this  configuration  record  is  also  wrong  in  the  tool  set  summary.  The 
following  table  shows  the  correct  information. 
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Name 


Offset 


Type 


Definition 


ReadConf  igRec  (configuration  record  for  ReadKeyMicroData) 
rcADBAddr  $0000 


rcLayoutOrLang 


rcRepeatDelay  $0002 


Byte 


$0001 


Byte 


ADB  keyboard  and  mouse  addresses 

low  nibble  -  keyboard 

high  nibble  -  mouse 

Byte  Keyboard  layout  and 

display  language 

low  nibble  -  keyboard  layout 

high  nibble  -  display  language 

Repeat  rate  and  delay 

low  nibble  -  repeat  rate 

high  nibble  -  repeat  delay 


Clarification 

This  section  presents  new  information  about  the  AsyncADBReceive  call. 

You  can  call  AsyncADBReceive  to  poll  a  device  using  register  2,  and  it  will  return  certain 
useful  information  about  the  status  of  the  keyboard.  The  call  returns  the  following 
information  in  the  specified  bits  of  register  2: 

Bit  5:    0-Caps  Lock  key  down 
1-Caps  Lock  key  up 

Bit  3:    0-Control  key  down 
1-Control  key  up 

Bit  2:     0-Shift  key  down 
1-Shift  key  up 

Bit  1:     0-Option  key  down 
1-Option  key  up 

Bit  0:    0-Command  key  down 
1-Command  key  up 
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Control  Manager 

The  following  sections  correct  errors  or  omissions  in  Chapter  4,  "Control  Manager,"  in 
Volume  1  of  the  Toolbox  Reference. 


Error  corrections 

This  section  documents  errors  in  Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox 
Reference. 

■  The  color  table  for  the  size  box  control  in  the  Toolbox  Reference  is  incorrect.  The 
correct  table  follows,  with  new  information  in  boldface. 

growoutiine  word  Color  of  size  box's  outline 

Bits  8-15  -  zero 

Bits  4-7  =  outline  color 

Bits  0-3  -  zero 

growNorBack  word  Color  of  interior  when  not  highlighted 

Bits  8-15  =  zero 

Bits  4-7  =  background  color 

Bits  0-3  -  icon  color 

growSeiBack  word  Color  of  interior  when  highlighted 

Bits  8-15  =  zero 

Bits  4-7  =  background  color 

Bits  0-3  =  icon  color 

■  On  page  4-76  of  the  Toolbox  Reference,  in  the  section  that  covers  the  setctiParams 
call,  it  states  that  the  call  "Sets  new  parameters  to  the  control's  definition 
procedure . . ."  This  description  is  misleading;  the  call  does  not  directly  set  the 
parameters.  Rather,  it  sends  the  new  parameters  to  the  control's  definition  procedure, 
unlike  setctivalue,  which  actually  sets  the  appropriate  value  in  the  control  record 
and  then  passes  the  value  on  to  the  definition  procedure. 
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Clarifications 

The  following  items  provide  additional  information  about  features  previously  described 
in  the  Toolbox  Reference. 

■  The  barArrowBack  entry  in  the  scroll  bar  table  was  never  implemented  as  first 
intended,  and  is  now  no  longer  used. 

■  The  Control  Manager  preserves  the  current  port  across  Control  Manager  calls,  including 
those  that  are  passed  through  other  tools,  such  as  the  Dialog  Manager. 

■  The  Control  Manager  preserves  the  following  fields  in  the  port  of  a  window  that 
contains  controls: 

bkPat  background  pattern 

pnLoc  pen  location 

pnsize  pen  si2e 

pnMode  pen  mode 

pnPat  pen  pattern 

pnMask  pen  mask 

pnvis  pen  visibility 

f  ontHandie  handle  of  current  font 

font  id  ID  of  current  font 

fontFlags  font  flags 

txsize  text  size 

txFace  text  face 

txMode  text  mode 

spExtra  value  of  space  extra 

chExtra  value  of  character  extra 

f  gCoior  foreground  color 

bgcolor  background  color 

■  The  control  definition  procedures  for  simple  buttons,  check  boxes,  and  radio  buttons 
can  now  compute  the  size  of  their  boundary  rectangles  automatically.  The  computed 
size  is  based  on  the  size  of  the  title  string  for  the  button. 

■  To  ensure  predictable  color  behavior,  you  should  always  align  color  table-based 
controls  on  an  even  pixel  boundary  in  640  mode.  If  you  do  not  do  so,  the  control  will 
not  appear  in  the  colors  you  specify,  due  to  the  effect  of  dithering. 
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Dialog  Manager 

The  following  sections  correct  errors  or  omissions  in  Chapter  6,  "Dialog  Manager,"  in 
Volume  1  of  the  Toolbox  Reference. 


Error  corrections 

This  section  explains  changes  that  have  been  made  to  the  Dialog  Manager's 
documentation  in  the  Apple  IIGS  Toolbox  Reference. 

m   The  documentation  for  setDitemType  on  page  6-82  of  the  Toolbox  Reference  says 
that  the  call  is  used  to  change  a  dialog  item  to  a  different  type.  In  fact, 
SetDitemType  should  be  used  only  to  change  the  state  of  an  item  from  enabled  to 
disabled  or  vice  versa. 

■   The  Dialog  Manager  does  not  support  dialog  item  type  values  of  picitem  or 
icon i  tem,  contrary  to  what  the  Toolbox  Reference  states  in  Table  6-3  on  page  6-12. 
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Integer  Math  Tool  Set 


The  following  section  describes  a  bug  that  has  been  fixed  in  the  Integer  Math  Tool  Set. 


Clarifications 

■   The  Long2Dec  Integer  Math  tool  call  now  correctly  handles  input  long  values  that  have 
the  low-order  three  bytes  set  to  zero.  Previously,  if  the  input  long  had  its  low-order 
three  bytes  set  to  zero,  Long2Dec  would  always  return  a  zero  value,  even  if  the  high- 
order  byte  was  non-zero. 
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List  Manager 

The  following  sections  correct  errors  or  omissions  in  Chapter  11,  "List  Manager,"  in  Volume 
1  of  the  Toolbox  Reference. 


Clarifications 


■  The  Apple  IIGS  Toolbox  Reference  states  that  a  disabled  item  of  a  list  cannot  be 
selected.  In  fact,  a  disabled  item  can  be  selected,  but  it  cannot  be  highlighted.  The 
List  Manager  provides  the  ability  to  select  disabled  (dimmed)  items  so  that  it  is 
possible,  for  instance,  for  a  user  to  select  a  disabled  menu  choice  as  part  of  a  help 
dialog.  To  make  an  item  unselectable,  set  it  inactive  (see  "List  Manager  definitions" 
later  in  this  chapter). 

■  Any  List  Manager  tool  call  that  draws  will  change  fields  in  the  GrafPort.  If  you  are  using 
List  Manager  tool  calls  you  must  set  up  the  GrafPort  correctly  and  save  any  valuable 
GrafPort  data  before  issuing  the  call. 

■  Member  text  is  now  drawn  in  16  colors  in  both  320  and  640  mode. 

■  Previous  versions  of  List  Manager  documentation  do  not  clearly  define  the  relationship 
between  the  listview,  listMemHeight,  and  listRect  fields  in  the  list  record. 
To  clarify  this  point,  note  that  the  following  formula  must  be  true  for  values  in  any  list 
record: 

listview  'listMemHeight  +  2  -  listRect.v2   -listRect.vl 

If  you  set  listview  to  0,  the  List  Manager  will  automatically  adjust  the 
iistRect.v2  field  and  set  the  listview  field  so  that  this  formula  holds.  Note  that 
if  you  pass  a  0  value  for  listview  the  bottom  boundary  of  listRect  may  change 
slightly. 

list  Manager  definitions 

The  following  terms  define  the  valid  states  for  a  list  item. 

inactive  Bit  5  of  the  list  item's  memFlag  field  is  set  to  1.  Inactive  items  appear 

dimmed  and  cannot  be  highlighted  or  selected. 

disabled  Bit  6  of  the  list  item's  memFlag  field  is  set  to  1.  Disabled  items  appear 

dimmed  and  cannot  be  highlighted. 


F-8       Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  I1GS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


enabled  Bit  6  of  the  list  item's  memFiag  field  is  set  to  0.  Enabled  items  appear 

normal  and  can  be  highlighted. 

selected  Bit  7  of  the  list  item's  memFiag  field  is  set  to  1.  This  bit  is  set  when  a 

user  clicks  on  the  list  item,  or  the  item  is  within  a  range  of  selected  items. 
A  selected  item  appears  highlighted  only  if  it  is  also  enabled. 

highlighted  A  member  of  a  list  appears  highlighted  only  when  it  is  both  selected  and 

enabled.  This  means  that  bit  7  of  the  memFiag  field  is  set  to  1  and  bit  6 
is  set  to  0.  A  highlighted  member  is  drawn  in  the  highlight  colors. 
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Memory  Manager 

The  following  sections  correct  errors  or  omissions  in  Chapter  12,  "Memory  Manager,"  in 
Volume  1  of  the  Toolbox  Reference. 


Error  correction 

On  page  12-10  of  the  Toolbox  Reference,  Figure  12-7  shows  the  low-order  bit  of  the  User  ID 
is  reserved.  This  is  not  correct.  The  figure  should  show  that  the  maim d  field  comprises 
bits  0-7,  and  that  the  mainiD  value  of  $00  is  reserved. 


Clarification 

The  Toolbox  Reference  documentation  of  the  SetHandiesize  call  ($1902)  states  "If  you 
need  more  room  to  lengthen  a  block,  you  may  compact  memory  or  purge  blocks."  This  is 
misleading.  In  fact,  to  satisfy  a  request  the  Memory  Manager  will  compact  memory  or 
purge  blocks  in  order  to  free  sufficient  contiguous  memory.  Therefore,  the  sentence 
should  read  "If  your  request  requires  more  memory  than  is  available,  the  Memory  Manager 
may  compact  memory  or  purge  blocks,  as  needed." 
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Menu  Manager 

The  following  sections  correct  errors  or  omissions  in  Chapter  13,  "Menu  Manager,"  in 
Volume  1  of  the  Toolbox  Reference. 


Error  corrections 

■  In  the  description  of  the  SetSysBar  tool  call  (pages  13-86  and  13-3),  the  Toolbox 
Reference  states  that,  after  an  application  issues  this  call,  the  new  system  menu  bar 
becomes  the  current  menu  bar.  This  is  incorrect.  Your  application  must  issue  the 
SetMenuBar  tool  call  to  make  the  new  menu  bar  the  current  menu  bar. 

■  In  the  definition  of  the  menu  bar  record  (pages  13-17-18),  the  Toolbox  Reference  shows 
that  bits  0-5  of  the  ctiFlag  field  are  used  to  indicate  the  starting  position  for  the 
first  title  in  the  menu  bar.  This  is  incorrect.  ThectiHiiite  field  defines  the  starting 
position  for  the  first  tide.  Note  further  that  the  entire  ctiHiiite  field  is  used  in  this 
manner.  The  documented  purpose  ofthectiHiiite  field  (number  of  highlighted 
titles)  is  not  supported  by  the  Menu  Bar  record. 


Clarifications 

■  The  setBarCoiors  tool  call  changes  the  color  table  for  all  menu  bars  in  a  window.  If 
you  want  to  use  separate  color  tables  for  different  menu  bars,,  your  application  must 
build  a  menu  bar  color  table  and  modify  the  cticoior  field  of  the  appropriate 
control  record  to  point  to  this  custom  color  table.  See  "SetBarColor"  in 

Chapter  13,  "Menu  Manager,"  of  the  Toolbox  Reference  for  the  format  and  contents  of  a 
menu  bar  color  table. 

■  The  description  of  the  insertMenu  tool  call  should  also  note  that  your  application 
must  call  FixMenuBar  before  calling  DrawMenuBar  in  order  to  display  the  modified 
menu  bar. 

■  The  description  of  the  mitPaiette  tool  call  in  the  Toolbox  Reference  should  also 
note  that  the  call  changes  color  tables  1  through  6  to  correspond  to  the  colors  needed 
for  drawing  the  Apple  logo  in  its  standard  colors. 

■  The  caicMenuSize  call  uses  the  newWidth  and  newHeight  parameters  to  compute  a 
menu's  size.  These  parameters  may  contain  the  width  and  height  of  the  menu,  or  may 
contain  the  values  $0000  or  $FFFF.  A  value  of  $0000  tells  CaicMenuSize  to  calculate 
the  parameter  automatically.  A  value  of  $FFFF  tells  it  to  calculate  the  parameter  only  if 
the  current  setting  is  0. 
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The  effect  of  all  three  uses: 

d   Pass  the  new  value.  The  value  passed  will  become  the  menu's  size.  Use  this 
method  when  a  specific  menu  size  is  needed. 

d   Pass  $0000.  The  size  value  will  be  automatically  computed.  This  option  is  useful  if 
menu  items  are  added  or  deleted,  rendering  the  menu's  size  incorrect.  The  menu's 
height  and  width  can  be  automatically  adjusted  by  calling  caicMenuSize  with 
newWidth  and  newHeight  equal  to  $0000. 

o   Pass  $FFFF.  The  width  and  height  of  a  menu  is  0  when  it  is  created.  FixMenuBar 
calls  CaicMenuSize  with  newWidth  and  newHeight  equal  to  $FFFF  to  calculate 
the  sizes  of  those  menus  with  heights  and  widths  of  0. 


F-12      Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  1IGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Miscellaneous  Tool  Set 

The  following  sections  correct  errors  or  omissions  in  Chapter  14,  "Miscellaneous  Tool  Set," 
in  Volume  1  of  the  Toolbox  Reference. 


Error  corrections 


On  page  14-58  of  the  Toolbox  Reference,  Figure  14-3  shows  the  low-order  bit  of  the  User 
ID  is  reserved.  This  is  not  correct.  The  figure  should  show  that  the  ma  in  id  field 
comprises  bits  0-7,  and  that  the  mainiD  value  of  $00  is  reserved. 

The  sample  code  on  page  14-28  contains  an  error.  In  the  code  to  clear  the  1  second  IRQ 
source,  the  second  instruction  reads 

TSB        $C032 

This  instruction  should  read 

TRB         $C032 

The  descriptions  of  the  PackBytes  and  unPackBytes  tool  calls  in  unclear  with 
respect  to  the  startHandle  parameter  to  each  call.  The  stack  diagrams  correctly 
describe  the  parameter  as  a  pointer  to  a  pointer.  However,  the  C  sample  code  for  each 
call  defines  startHandle  as  a  handle.  In  both  cases,  startHandle  is  not  a  Memory 
Manager  handle,  but  is  a  pointer  to  a  pointer.  Creating  startHandle  as  a  handle  will 
cause  unpredictable  system  behavior. 
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Print  Manager 

The  following  sections  correct  errors  or  omissions  in  Chapter  15,  "Print  Manager,"  in 
Volume  1  of  the  Toolbox  Reference. 


Error  corrections 


This  section  documents  errors  in  the  Toolbox  Reference. 

u   The  diagram  for  the  job  subrecord,  figure  15-10  on  page  15-14  of  the  Toolbox  Reference, 
shows  that  the  fFromUsr  field  is  a  word.  This  is  incorrect.  The  f  FromUsr  field  is 
actually  a  byte.  Note  that  the  offsets  for  all  fields  following  this  one  are  incorrect,  as  a 
result.  This  error  is  also  reflected  in  the  tool  set  summary  at  the  end  of  the  chapter. 

■   The  description  of  the  Pr  jobDialog  tool  call  states  that  "The  initial  settings 

displayed  in  the  dialog  box  are  taken  from  the  printer  driver . . .."  This  is  incorrect.  The 
sentence  should  begin  "The  initial  settings  displayed  in  the  dialog  box  are  taken  from 
the  print  record 


Clarifications 

■   The  existing  Toolbox  Reference  documentation  for  the  PrPicFile  tool  call  does  not 
mention  that  your  program  may  pass  a  NIL  value  for  statusRecPtr.  Passing  a  NIL  pointer 
causes  the  system  to  allocate  and  manage  the  status  record  internally. 
The  PrPixeiMap  call  (documented  in  Volume  1  of  the  Toolbox  Reference)  provides  an 
easy  way  to  print  a  bitmap.  It  does  much  of  the  required  processing,  and  an 
application  need  not  make  the  calls  normally  required  to  start  and  end  the  print  loop. 
The  srcLocPtr  parameter  must  be  a  pointer  to  a  loclnfo  record  (see  Figure  16-3  in 
Chapter  16,  "QuickDraw  n,"  in  the  Toolbox  Reference  for  the  layout  of  the  loclnfo 
record). 
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QuickDraw  n 

The  following  sections  correct  errors  or  omissions  in  Chapter  16,  "QuickDraw  II,"  in 
Volume  2  of  the  Toolbox  Reference. 


Error  corrections 

The  following  items  provide  corrections  to  the  documentation  for  QuickDraw  II  in  the 
Apple  IIGS  Toolbox  Reference: 

■  The  documentation  in  the  Toolbox  Reference  that  explains  pen  modes  is  somewhat 
misleading.  There  are,  in  fact,  8  drawing  modes,  and  you  may  set  the  pen  to  draw  lines 
and  other  elements  of  graphics  in  any  of  these  modes.  There  are  also  16  modes  used  for 
drawing  text,  and  they  are  completely  independent  of  the  graphic  pen  modes.  The  8 
drawing  modes  listed  in  Table  16-9  on  page  16-235  are  valid  modes  for  either  the  text 
pen  or  the  graphics  pen.  You  can  set  either  pen  to  any  of  these  modes  by  using  the 
appropriate  calls.  You  can  also  set  the  text  pen  to  8  other  modes.  These  modes  are 
listed  in  the  table  on  page  16-260  of  the  Toolbox  Reference.  The  setPenMode  call  sets 
the  mode  used  by  the  graphics  pen;  the  setTextMode  call  sets  the  mode  used  by  the 
text  pen.  Setting  either  one  does  not  affect  the  other. 

■  There  are  two  versions  of  the  Apple  IIGS  standard  640-mode  color  tables,  one  on  page 
16-36  and  one  on  page  16-159.  The  two  tables  are  different;  Table  16-7  on  page  16-159 
is  correct. 

■  In  the  QuickDraw  n  chapter,  the  Apple  IIGS  Toolbox  Reference  states  that  the 
coordinates  passed  to  the  LineTo  and  MoveTo  calls  should  be  expressed  as  global 
coordinates.  In  fact,  the  coordinates  must  be  local  coordinates,  and  must  refer  to  the 
GrafPort  in  which  the  drawing  or  moving  takes  place. 
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Sound  Tool  Set 

The  following  sections  correct  errors  or  omissions  in  Chapter  20,  "Sound  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference. 


Error  corrections 

This  section  provides  corrections  to  the  documentation  of  the  Sound  Tool  Set  in  the 
Apple  IIGS  Toolbox  Reference. 

m   The  documentation  of  the  ffs  oundDoneStatus  call  includes  an  error.  You  will  note 
that  the  paragraph  that  describes  the  call  does  not  agree  with  the  "Stack  after  call" 
diagram.  The  text  states  that  the  call  returns  TRUE  if  the  specified  sound  is  still 
playing,  whereas  the  diagram  states  that  it  returns  FALSE  if  still  playing.  The  diagram, 
not  the  text,  is  correct. 

■   There  is  an  undocumented  distinction  between  a  generator  that  is  playing  a  sound  and 
one  that  is  active.  A  generator  that  is  playing  a  sound  returns  FALSE  in  response  to  an 
FFSoundDoneStatus  call.  One  that  is  active  may  or  may  not  be  playing  a  sound;  the 
value  of  the  flag  returned  by  FFSoundstatus  is  TRUE.  Active  generators  are  those 
that  are  allocated  to  a  voice.  At  any  given  moment  the  generator  may  be  playing  a 
sound,  and  so  the  FFSoundDoneStatus  returns  FALSE— or  it  may  be  silent  between 
notes,  in  which  case  FFSoundDoneStatus  returns  TRUE. 


Clarification 

This  section  presents  more  complete  information  about  the  FFStartsound  tool  call, 
including  further  explanation  of  its  parameters,  a  new  error  code,  an  example  procedure 
for  moving  a  sound  from  the  Macintosh  to  the  Apple  IIGS  and  some  sample  code 
demonstrating  the  use  of  the  call.  The  original  documentation  for  this  call  is  in 
Chapter  20,  "Sound  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference. 
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FFS tart Sound 

The  freeform  synthsizer  is  designed  to  play  back  long  wave  forms.  In  order  to  handle 
longer  waveforms  the  synthesizer  uses  two  buffers  (which  must  be  the  same  size), 
alternating  its  input  from  one  to  the  other.  When  the  synthesizer  exhausts  a  buffer,  it 
generates  an  interrupt  and  then  starts  reading  data  from  the  other  buffer.  The  Sound  Tool 
Set  services  the  interrupt  and  begins  refilling  the  empty  buffer.  This  process  continues 
until  the  waveform  has  been  completely  played. 

Note  that  all  synthesizer  input  buffers  must  be  buffer-size  aligned.  That  is,  if  you  have 
allocated  4K  buffers,  then  those  buffers  must  be  aligned  on  4K  memory  boundaries. 

Parameter  Block 


$00 

waveStart 

— 

Long 

$04 

waveSize 

- 

Word 

$06 

freqOffset 

- 

Word 

$08 

—           docBuffer           - 

Word 

$0A 

- 

bufferSize 

Word 

$0C 

nextWavePtr 

Long 

$10 

volSetting 

Word 

waveStart  The  starting  address  of  the  wave  to  be  played,  not  in  DOC  RAM  but  in 

Apple  IIGS  system  RAM.  The  Sound  Tool  Set  loads  the  waveform  data 
into  DOC  RAM  as  it  is  played. 

waveSize  The  size  in  pages  of  the  wave  to  be  played.  A  value  of  1  indicates  that 

the  wave  is  one  page  (256  bytes)  in  size;  a  value  of  2  indicates  that  it 
is  two  pages  (512  bytes)  in  size— and  so  on  as  you  might  expect.  The 
only  anomaly  is  that  a  value  of  0  specifies  that  the  wave  is  65,536 
pages  in  size. 
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freqOff set 


docBuffer 


bufferSize 


nextWavePtr 


volSetting 


New  error  code 


This  parameter  is  copied  directly  into  the  Frequency  High  and 
Frequency  Low  registers  of  the  DOC.  See  the  previous  discussion  of 
those  registers  for  more  complete  information. 

Contains  the  address  in  Sound  RAM  where  buffers  are  to  be  allocated. 
This  value  is  written  to  the  DOC  WaveForm  Table  Pointer  register.  The 
low-order  byte  is  not  used,  and  should  always  be  set  to  0. 

The  lowest  three  bits  set  the  values  for  the  table-size  and  resolution 
portions  of  the  DOC  Bank-Select/Table-size/Resolution  register.  See 
the  previous  discussion  of  that  register  for  details. 

This  is  the  address  of  the  next  waveform  to  be  played.  If  the  field's 
value  is  0,  then  the  current  waveform  is  the  last  waveform  to  be 
played. 

The  low  byte  of  the  volSetting  field  is  copied  directly  into  the 
Volume  register  of  the  DOC.  All  possible  byte  values  are  valid. 


$0817        iRQNotAssignedErr      No  master  IRQ  was  assigned. 
Moving  a  sound  from  the  Macintosh  to  the  Apple  IIGS 

To  move  a  digitized  sound  from  the  Macintosh  to  the  Apple  IIGS  and  play  the  sound,  you 
will  have  to  perform  the  following  steps 

1.  Save  the  sound  as  a  pure  data  file  on  the  Macintosh. 

2.  Transfer  the  file  to  the  Apple  IIGS  (using  Apple  File  Exchange,  for  example). 

3.  Filter  all  the  zero  sample  bytes  out  of  the  file  by  replacing  them  with  bytes  set  to  $01. 
This  is  very  important,  because  the  Apple  IIGS  interprets  zero  bytes  as  the  end  of  a 
sample. 

4.  Load  the  sound  into  memory  with  GS/OS  calls. 

5.  Play  the  sound  with  the  FFStartsound  tool  call. 

Set  the  f  reqof  f  set  parameter  to  $01B7  in  order  to  play  the  sound  at  the  same 
tempo  as  the  Macintosh. 
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Sample  code 

This  assembly-language  code  sample  demonstrates  the  use  of  the  FFStartsound  tool 
call. 


PushWord    chanGenType 
PushLong    #STParamBlk 
FFStartSound 


;  set  generator  for  FFSynth 
;  address  of  parm  block 
;  start  free-from  synth 


ChanGenType  DC.W  $0201 


;  generator  2,  FFSynth 


STParamBlk   DS.L  1 


Entry 

WaveSize 

WaveSize 

DS.W  1 

Freq 

DC.W  $200 

Start 

DC.W  $8000 

Size 

DC.W  $6 

Nxtwave 

DC. I,  $0 

Vol 

DC.W  $FF 

store  the  address  of  the 
sound  in  system  memory  here 

store  the  number  of  pages  to 

play  here 
A9  set  for  each  sample  once 
start  at  beginning 
16k  buffers 
no  new  param  block 
maximum  volume 
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Window  Manager 

The  following  sections  correct  errors  or  omissions  in  Chapter  25,  "Window  Manager,"  in 
Volume  2  of  the  Toolbox  Reference. 


Error  corrections 

This  section  corrects  some  errors  in  the  Window  Manager  documentation  in  the  Apple  IIGS 
Toolbox  Reference. 

■  The  manual's  description  of  SetzoomRect  is  incorrect.  The  correct  description  is  as 
follows: 

Sets  the  f  zoomed  bit  of  the  window's  wFrame  record  to  0.  The  rectangle  passed  to 
SetzoomRect  then  becomes  the  window's  zoom  rectangle.  The  window's  size  and 
position  when  SetzoomRect  is  called  becomes  the  window's  unzoomed  size  and 
position,  regardless  of  what  the  unzoomed  characteristics  were  before  SetzoomRect 
was  called. 

■  Apple  IIGS  Toolbox  Reference  page  25-126,  third  line: 

If  wmTaskMask  bittmlnfo  (bit  15)  "  1 

should  read: 

If  wmTaskMask  bittmlnfo  (bit  15)  "  0 

■  When  used  with  a  window  that  does  not  have  scroll  bars,  the  call  windNewRes  calls  the 
window's  defProc  to  recompute  window  regions.  A  call  to  sizewindow  is  not 
necessary  under  these  circumstances. 
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ACIA:  See  Asynchronous  Communications 
Interface  Adapter. 

Adaptive  Differential  Pulse  Code  Modulation 
(ADPCM):  An  algorithm  for  digitizing  audio 
samples.  Used  in  the  Apple  IIGS  Audio 
Compression  and  Expansion  Tool  Set  for 
compressing  audio  samples. 

ADPCM:  See  Adaptive  Differential  Pulse  Code 
Modulation. 

ADSR:  Acronym  for  attack,  decay,  sustain, 
release.  These  terms  describe  the  paradigm  for 
representing  sounds  in  terms  of  a  sound 
envelope. 

alert  window:  Similar  to  a  modal  dialog  box; 
used  to  present  urgent  or  important  information 
to  the  user.  You  create  alert  windows  with  the 
Alertwindow  Window  Manager  tool  call. 

Asynchronous  Communications  Interface 
Adapter  (ACIA):  Adapter  card  that  allows  the 
Apple  IIGS  to  support  asynchronous 
communications  protocols  with  external 
devices. 

attack:  That  portion  of  a  sound  envelope  where 
the  sound  is  increasing  from  silence  to  its  peak 
loudness.  See  also  ADSR. 

control  template:  Structure  containing  the 
information  necessary  for  the  NewControi2 
Control  Manager  tool  call  to  create  a  new 
control. 

decay:  That  portion  of  a  sound  envelope  where 
the  sound  falls  off  from  its  peak  loudness  to  a 
sustained  level.  See  also  ADSR. 

Digital  Oscillator  Chip  (DOC):  Integrated 
circuit  that  supports  the  sound  capabilities  of 
the  Apple  IIGS. 

DOC:  See  Digital  Oscillator  Chip. 

drop  sample  tuning:  Describes  a  technique  for 
changing  the  pitch  of  a  played  sound  that  relies 
on  skipping  (or  dropping)  sound  samples  on 


playback.  By  dropping  samples  at  a  fixed  rate, 
the  pitch  of  a  sound  can  be  raised  in  octave 
increments. 

envelope:  A  graphical  representation  of  a 
sound's  loudness  over  time.  The  envelope 
typically  consists  of  segments  identified  as 
attack,  decay,  sustain  and  release,  or  ADSR. 

extended  controls:  Controls  created  with  the 
NewControi2  Control  Manager  tool  call,  rather 
than  the  Newcontroi  call.  Extended  controls 
have  new-style  control  records  that  contain 
more  information  than  those  created  by 
NewControl. 

keystroke  equivalent:  A  keystroke  that 
activates  a  control  just  as  if  the  user  had  clicked 
in  the  control. 

menu  template:  Data  structure  used  to  define 
menus,  menu  items,  and  menu  bars  to  the  Menu 
Manager. 

MIDI:  See  Musical  Instrument  Digital 
Interface. 

Musical  Instrument  Digital  Interface 
(MIDI):  An  interface  specification  that  allows 
external  devices  to  control  electronic  musical 
instruments. 

out-of-memory  queue:  A  queue  maintained  by 
the  Memory  Manager.  Queue  elements  (out-of- 
memory  routines)  refer  to  code  to  be 
executed  when  the  Memory  Manager  detects  an 
out-of-memory  condition. 

out-of-memory  routines:  Code  executed  by 
the  Memory  Manager  when  it  detects  an  out-of- 
memory  condition.  The  out-of-memory  queue 
consists  of  a  list  of  these  routines. 

password  field:  Do  not  echo  user  input, 
allowing  protected  data  entry.  Your  program  can 
specify  the  echo  character;  the  default  echo 
character  is  asterisk  (*). 

pop-up  menu:  A  menu  that  "pops"  out  of  its 
display  rectangle  when  selected  by  the  user.  The 
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two  types  of  pop-up  menus,  type  1  and  type  2 
pop-up  menus,  have  different  limits  on  their 
maximum  size. 

reference  type:  Indicates  whether  a  storage 
location  contains  a  pointer,  a  handle,  or  a 
resource  ID  for  an  object. 

release:  That  portion  of  a  sound  envelope 
where  the  note  dies  away  to  silence.  See  also 
ADSR. 

resource:  Collection  of  data  managed  by  the 
Resource  Manager  for  other  applications. 

resource  file:  A  collection  of  one  or  more 
resources.  The  Resource  Manager  provides 
routines  for  accessing  and  updating  resources  in 
a  resource  file. 

resource  ID:  Uniquely  identifies  a  resource 
within  the  context  of  its  resource  type.  The 
Resource  Manager  provides  facilities  to  assign 
unique  resource  IDs.  Compare  resource  name. 

resource  name:  Uniquely  identifies  a  resource 
within  the  context  of  its  resource  type.  Note 
that  resource  names  are  not  maintained  by  the 
system;  it  is  your  program's  responsibility  to 
assign  and  manage  them.  Compare  resource  ID. 

resource  type:  Identifies  a  class  of  resources 
that  share  a  common  data  layout.  Individual 
instances  of  resources  of  a  given  type  are 
identified  by  their  unique  resource  ID  or 
resource  name. 

run  item:  An  element  in  the  run  queue.  Run 

items  specify  program  code  to  be  executed  by 
the  Desk  Manager  at  regular  intervals. 

run  queue:  A  queue  maintained  by  the  Desk 
Manager  that  contains  elements  (run  items) 
that  specify  code  to  be  executed  at  regular 
intervals. 

sample  rate:  Specifies  the  number  of  sound 
samples  the  Apple  IIGS  DOC  plays  per  second. 


sustain:  That  portion  of  a  sound  envelope 
where  the  note  maintains  a  fairly  constant 
loudness,  before  it  dies  away.  See  also  ADSR. 

target  control:  That  control  which  is  currently 
the  recepient  of  user  actions  (keystrokes  and 
menu  items). 

TextEdit  record:  Describes  a  TextEdit  user 
session,  whether  or  not  that  session  is  managed 
as  a  control. 

type  1  pop-up  menu:  A  pop-up  menu  that  will 
not  grow  beyond  its  window  constraints. 
Compare  type  2  pop-up  menu. 

type  2  pop-up  menu:  A  pop-up  menu  that  will 
grow  beyond  its  window  if  necessary  to  display 
its  menu  items.  Compare  type  1  pop-up  menu. 
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Index 


A/D  converter  register 
Sound  Tool  Set  and  47- 16 

acceleration,  of  MIDI  Tool  calls  38- 
20 

ACEBootlnit  27-  5 

ACECompBegin  27- 12 

ACECompress  27- 13 

ACEExpand  27- 15 

ACEExpBegin  27- 17 

ACEInfo  27- 11 

ACEReset27-9 

ACEShutDown  27- 7 

ACEStartUp  27-  6 

ACEStatus  27- 10 

ACEVersion  27-  8 

activating  TextEdit  records  49-  74 

Adaptive  Differential  Pulse  Code 
Modulation  (ADPCM)  27-  3 

adding  items  to  a  menu  37-  23 

AddResource  45-  34 

AddToOOMQueue  36-  8 

AddToQueue  39-  3,  5 

AddToRunQ  29-  6 

ADPCM  See  Adaptive  Differential 
Pulse  Code  Modulation 

alert  windows 

button  strings  52-  8 
example  52- 10 
icon  number  52-  7 
message  text  52-  8 
separator  character  52-  8 
size  characters  52-  6 
special  characters  52-  9 
terminator  character  52-  8 

alert  windows  52-  5-11 

alert  windows  E-  2 

AlertWindow  52-  22 

AllNotesOff41-20 

allocating  TextEdit  records  49- 104 

AllocGen41-2,21 

AppleShare  and  Standard  File  48-  3 

AppleTalk  print  zone  42- 14 

AppleTalk,  MIDI  Tool  Set  and  38-  22 


application  switchers 

and  Resource  Manager  45-  26,  41, 
66 
attack  41-  3 

attack,  decay,  sustain,  release  41-  2 
auto-key  events,  limit  on  31-  6 
aWaveCount,  Note  Synthesizer 
parameter  41-  9 

B 

bank  select  bit 

Sound  Tool  Set  and  47- 16 
bank-select/table-size/resolution 
register 
Sound  Tool  Set  and  47- 14 
boundary  rectangle 

automatically  computed  for 

some  controls  28-  3 
automatically  computed  for 

some  controls  F-  5 
control  definition  procedures  28- 
16 
bounds,  control  definition 

procedure  routine  28- 16 
breakpoints  and  increments  in 

sound  envelopes  41- 4 
button  strings,  in  alert  windows  52-  8 
bWaveCount,  Note  Synthesizer 
parameter  41-  9 


C  strings,  as  resources  E-  45 

caching  custom  menus  37-  7 

caching  menus  37-  6 

CalcMask43-3 

CallQIDefProc  28-  21 

CallRoutine  command,  Note 
Sequencer  40- 11 

changing  window  size,  and  controls 
52-4 

channel  register 

Sound  Tool  Set  and  47- 14 

check  box  control 
control  template  28-  51 
extended  control  record  28-  98 


new  features  28-7 
check  box  control  template  E- 13 
ChooseFont  bugfix  32-  2 
choosing  printers  42-  3 
classic  desk  accessories  29-  2, 8 
ClearHeartBeat  39-  2 
Clearlncr  40-  45 

clearing  TextEdit  selection  49-  75 
CloseResourceFile  45-  36 
CMLoadResource  28-  23 
CMReleaseResource  28-  24 
color  behavior  and  even  pixel 

alignment  28-  3 
color  behavior  and  even  pixel 

alignment  F-  5 
color  tables 

640  mode  43-  2 

640  mode  F-  15 

menu  bars  37-  2 

menu  bars  F-  11 

now  use  4  bits  for  640  mode  28-  4 

size  box  control  28-  2 

size  box  control  F-  4 
command  interpreter,  Note 

Sequencer  40-  5 
common  style  record,  TextEdit  49- 

88 
CompileText  52-  24 
completion  routines,  Note 

Sequencer  40-  6,  54,  56 
compressing  TextEdit  records  49-  78 
compression  ratios,  in  ACE  Tool  Set 

27-2 
compression,  digital  audio  27-  2 
control  commands,  Note  Sequencer 

40-10 
control  definition  procedures 

bounds  routine  28- 16 

drag  routine  28- 13 

drawing  in  28- 13 

event  routine  28- 14 

initialize  routine  28-13 

new  messages  28- 12 

notify  multipart  routine  28- 19 

record  size  routine  28- 13 
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sending  messages  to  28-  35 
tab  routine  28- 18 
target  routine  28- 15 
window  change  routine  28-  20 
window  size  routine  28-17 
Control  Manager 

new  controls  28-  6 
control  register 

Sound  Tool  Set  and  47- 13 
control  template,  check  box  E- 13 
control  template,  icon  button  E- 15 
control  template,  LineEdit  E- 18 
control  template,  list  E-  20 
control  template,  picture  E-  24 
control  template,  pop-up  menu  E- 

26 
control  template,  radio  button  E-  30 
control  template,  scroll  bar  E-  32 
control  template,  simple  button  E- 

11 
control  template,  size  box  E-  34 
control  template,  static  text  E-  36 
control  template,  TextEdit  E-  38 
control  templates 

and  NewControl2  28-  42 
check  box  control  28-  51 
icon  button  control  28-  53 
LineEdit  control  28-  56 
list  control  28-  58, 61 
pop-up  menu  control  28-  63 
radio  button  control  28-  69 
sample  code  28-  83 
scroll  bar  control  28-  71 
simple  button  control  28-  49 
size  box  control  28-  73 
standard  header 

fCtlCanBeTarget  flag  28- 14, 

46 

fCtllsMultiPart  flag  28- 19, 

46 

fCtlProcRefNotPtr  flag  28- 

46 

fQlTarget  flag  28- 46 

fCtlTellAboutSizeflag28- 

46 

fCtlWantEvents  flag  28- 46 

fCtlWantsEvents  flag  28- 14 

flag  field  28- 45 

ID  field  28-  44 

moreFlags  field  28-  46 

pCount  field  28-  43 


procRef  field  28- 44 
rect  field  28-  44 

refConfield28-47 

standard  header  28-  43 

static  text  control  28-  75 

TextEdit  control  28-  77 

control  templates  28-  6, 42-88 

controls 

and  keystroke  processing  28-  4 
creating  28-  33 
target  28- 5, 18, 25, 31, 32, 36 
controls,  changes  in  drawing  28-  2 
controls,  changes  in  drawing  F-  4 
copying  text,  with  TextEdit  49-  79 
CountResources  45-  37 
CountTypes  45-  38 
CreateResourceFile  45-  39 
creating  menu  bars  37-  25 
creating  menus  37-  24 
creating  TextEdit  records  49- 104 
creating  windows  52-  32 
ctlChangeBounds  control  definition 

procedure  message  28- 16 
ctlChangeTarget  control  definition 

procedure  message  32 
ctlChangeTarget  control  definition 

procedure  message  28- 15 
ctlHandleEvent  control  definition 

procedure  message  36 
ctlHandleEvent  control  definition 

procedure  message  28- 14 
ctlHandleTab  control  definition 

procedure  message  28- 18 
ctllD  Control  Manager  field  93 
ctllD  Control  Manager  field  28-  26, 

27,38 
ctlMoreFlags  Control  Manager  field 

35,93 
ctlMoreFlags  Control  Manager  field 

28-  28, 39 
ctlNotifyMultiPart  control  definition 

procedure  message  28- 19 
ctlWindChangeSize  control 

definition  procedure  message 

28-17 
ctl WinStateChange  control  definition 

procedure  message  28-  20 
current  resource  file,  finding  45-  42 
cursorOffset,  TERecord  KeyRecord 

field  49- 23 
custom  menus  and  caching  37-  7 
cutting  text,  with  TextEdit  49-  80 


D 

data  structures,  TextEdit  49-  29 
deactivating  TextEdit  records  49-  81 
dead  key  translation  31-  4 
deallocating  TextEdit  records  49- 103 
DeAllocGen  41-  22 
Dec  Register  command,  Note 

Sequencer  40-17 
decay  41-  3 
defProcs  See  control  definition 

procedures 
DeleteFromQueue  39-  6 
DeleteHeartBeat  39-  2 
deleting  text,  with  TextEdit  49-  80 
desk  accessories 

and  Resource  Manager  45-  26,  41, 
66 
desk  accessories,  and  Control 

Manager  28-  29 
desk  accessories,  and  TaskMaster  52- 

4,39 
DetachResource  45-  40 
dialog  templates,  Standard  File  48- 12 
displaying  error  messages  52-  29 
displaying  menu  bar  37-  32 
DOC  memory  41- 10 
DOC  mode 

Sound  Tool  Set  and  47- 13 
DOC  registers 

reading  values  47-  21 
setting  values  47-  23 
Sound  Tool  Set  and  47- 11,  21,  23 
doEraseBuffer,  TextEdit  filter 

procedure  routine  49- 18 
doEraseRect,  TextEdit  filter 

procedure  routine  49-  17 
doRectChanged,  TextEdit  filter 

procedure  routine  49-  19 
draft  mode,  printing  42-  3 
drag,  control  definition  procedure 

routine  28- 13 
DrawInfoBar  52-  27 
drawing  controls,  changes  in  28-  2 
drawing  controls,  changes  in  F-  4 
DrawMember2  35-  5 
drop  sample  tuning 

Sound  Tool  Set  and  47- 10 


empty  menus,  creating  37-  4 
enabled,  list  items  35-  2 
enabled,  list  items  F-  9 
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EndFrameDrawing  52-  28 
envelopes  (sound)  See  sound 

envelopes 
error  handlers,  Note  Sequencer  40- 

6,54,56 
error  message  text  52-  44 
error  messages,  displaying  52-  29 
error  processing,  with  TextEdit  49-  84 
ErrorWindow  52-  29 
event,  control  definition  procedure 

routine  28- 14 
extended  control  records 
check  box  control  28-  98 
icon  button  control  28- 101 
LineEdit  control  28- 104 
list  control  28- 107 
picture  control  28- 110 
pop-up  menu  control  28-  113 
radio  button  control  28- 118 
scroll  bar  control  28- 121 
simple  button  control  28-  95 
size  box  control  28- 124 
standard  control  record 
ctlAction  field  28-  92 
ctlColorfield28-93 
ctlDatafield28-92 
ctlFlag  field  28-  91 
ctlHilite  field  28-  91 
ctllD  field  28-  93 
ctlMoreFlags  field  28-  93 
ctlNcxt  field  28- 91 
ctlOwnerfield28-91 
ctlProcfield28-92 
ctiRect  field  28-  91 
ctlRefConfield28-92 
ctlReservedfield28-93 
ctlValuefield28-91 
diversion  field  28- 94 
fCtlCanBeTargetflag28-93 
fCtllsMultiPart  flag  28-  94 
fCtlProcRefNotPtrflag28- 
94 
fOlTarget  flag  28- 15, 25, 31, 

93 

fCtlTellAboutSizeflag28- 

94 

fCtlWantEventsflag28-93 
standard  control  record  28-  89 
static  text  control  28- 127 
TextEdit  control  28- 131 


extended  control  records  28-  89-142 
extended  controls  28-  7 
extended  controls  28-  33, 89 


FASTFONT  43-  3 

fFromUser  Print  Manager  parameter 

42-2 
fFromUser  Print  Manager  parameter 

F- 14 
FFSetUpSound  47-  18 
FFSoundDoneStatus  47-  2 
FFSoundDoneStatus  F-  16 
FFStartPlaying  47-  20 
FFStartSound  47-  3 
FFStartSound  F-  17 
fidelity,  in  ADPCM  compression  27-  4 
file  name  separator  characters  48-  3 
file  prefixes  48-  2 
file  type  list  record,  Standard  File  48- 

9 
Filler  note  command,  Note 

Sequencer  40-  8 
filler  notes,  Note  Sequencer  40-  8 
filling  a  screen  region  with  a  pattern 

43-3,8 
filter  procedures  in  Standard  File  48- 

4 
filter  procedures,  TextEdit  See 

TextEdit:  filter  procedures  49- 
filtering  keystrokes,  in  TextEdit  49-  20 
filterProc,  TERecord  field  49- 16,  53 
filterProcPtr,  TEParamBlock  field  49- 

16 
filterProcPtr,  TEParamBlock  record 

field  49- 43 
FindTargetCtl  28-  25 
FMStartUp  changes  32-  2 
font  header  layout  43-  5 
free  memory  36-  9 
freeform  synthesizer  47-  3, 18,  20 
freeform  synthesizer  F- 17 
freeing  space  in  TextEdit  records  49- 

78 
frequency 

Sound  Tool  Set  and  47- 11 
frequency  registers 

Sound  Tool  Set  and  47- 12 


GCB  See  generator  control  block 

(GCB) 
GDRPrivate  52-  43 


generator  control  block  (GCB)  41- 11 
generators 

active  and  inactive  47-  2 

active  and  inactive  F- 16 

allocating  41-  21 

deallocating  41-  22 

Sound  Tool  Set  and  47-  9 
generators,  Note  Synthesizer  41-10 
GetCodeResConverter  39-  7 
GetCtlHandleFromID  28-  26 
GetCtllD  28-  27 
GetCtlMoreFlags  28-  28 
GetCtlParamPtr  28-  29 
GetCurResourceApp  45-  41 
GetCurResourceFile  45-  42 
GetlndResource  45-  43 
GetlndType  45-  45 
GetlnterruptState  39-  8 
GetlntStateRecSize  39-  9 
GetKeyTranslation  31-  5 
GetLEDefProc  34-  5 
GetLoc  40-  46 
GetMapHandle  45-  46 
GetOpenFileRefNum  45-  48 
GetPopUpDefProc  37-21 
GetResourceAttr  45-  9,  50 
GetResourceSize  45-  51 
GetROMResource  39-  9 
GetTimer  40-  47 
GetVector  39-  2 
GetWindowMgrGlobals  52-  31 
GS/OS  Class  1  input  strings,  as 

resources  Er  43 
GS/OS  Class  1  output  strings,  as 
resources  E-  44 

H 

heartbeat  task  39-  2 
HideMenuBar  37-22 
hiding  the  menu  bar  37-  22 
highlighted,  list  items  35-  3 
highlighted,  list  items  F-  9 
HomeResourceFile  45-  52 
hook  routines,  TextEdit  See  TextEdit: 

hook  routines  49- 
horizontal  scrolling,  and  TaskMaster 

52-3 

I 

icon  button  control 

control  record  28-  101 

control  template  28-  53 
icon  button  control  28-  6,  7 
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icon  button  control  template  E- 15 
icon  number,  in  alert  windows  52-  7 
icons,  as  resources  E-  46 
IfGo  Register  command,  Note 

Sequencer  40- 17 
inactive,  list  items  35-  2 
inactive,  list  items  F-  8 
Inc  Register  command,  Note 

Sequencer  40- 18 
initialize,  control  definition 

procedure  routine  28-13 
inserting  text,  with  TextEdit  49-  99 
InsertMItem2  37-23 
InstallWithStats32-3 
instrument  table 

setting  40- 50 
instrument  table  40-  50 
instruments 

assigning  to  tracks  40-  51 

Note  Synthesizer  41-  6 
instruments  40-  50 
interrupt  enable  bit 

Sound  Tool  Set  and  47- 13 
interrupt  state  information 

getting  39- 8 

getting  size  of  39- 9 

setting  39- 11 
interrupt  state  information  39-  4 
interrupts,  handling  sound  47-  6 
interrupts,  MIDI  Tool  Set  and  38-  22 
interrupts,  MIDI,  Sound  Tool  Set  and 

47-17 
InvalCtls28-30 
item  drawing  routines  in  Standard 

File  48- 5 
item  name,  menu,  setting  37-  30, 31 
item  numbers  for  lists  35-  4, 5, 8, 9, 10 


job  subrecord  42-  2 
job  subrecord  F-  14 
journaling  and  ReadMouse  31-  2 
joumaling  and  ReadMouse  39- 10 
Jump  command,  Note  Sequencer 

40-12 
justification  (text)  in  pictures  44-  2 
justification,  TextEdit  49-  3 

K 

keyboard  equivalent  37-  6 
keyboard  input  translation  31-  3,  5, 7 
keyboard  interface,  TextEdit  49- 11 


keyboard,  polling  for  status  of  keys 

26-3 
keyboard,  polling  for  status  of  keys  F- 

3 
keyFilter,  TERecord  field  49-  20,  58 
KeyRecord,  TextEdit  record  layout 

49-59 
keystroke  equivalent  37-  6 
keystroke  equivalent  E- 10 
keystroke  equivalents  28-  4, 48 
keystroke  equivalents  37-  8 
keystroke  equivalents  in  Standard 

File  dialogs  48-  4 
keystroke  processing  in  controls  28-  4 
keystroke  translation  31-  3, 5, 7 
keystroke  translation  E-  47 
keystroke  translation  tables,  as 

resources  E-  47 
killing  TextEdit  records  49- 103 


LineEdit  control 

control  record  28- 104 

control  template  28-  56 
LineEdit  control  28-  6, 8 
LineEdit  control  template  E- 18 
LineEdit  record,  new  layout  34-  2 
list  control 

control  record  28- 107 

control  template  28-  58,  61 
list  control  28-  6, 9 
list  control  template  E-  20 
list  controls  and  scroll  bars  35-  4 
list  item  numbers  35-  4, 5, 8, 9, 10 
List  Manager  and  Print  Manager  42-  3 
List  Manager  definitions  35-  2 
List  Manager  definitions  F-  8 
LoadAbsResource  45-  53 
loading  tool  sets,  and  version 

numbers  51-  2 
LoadResource  45-  55 
long  sequences,  compressing  27- 12, 

17 
Long2Dec  Integer  Math  tool  call  33-  2 
Long2Dec  Integer  Math  tool  call  F-  7 

M 

MakeNextQlTarget  28-  31 
MakeThisCtlTarget  28-  32 
MarkResourceChange  45-  57 
MatchResourceHandle  45-  58 
memory,  DOC  41- 10 
memory,  free  36-  9 


menu  bar 

creating  37-  25 

hiding  37-  22 
menu  bar  template  37-  20 
menu  bar  template,  as  resource  E- 

53 
menu  bar,  displaying  37-  32 
menu  caching  37-  6 
menu  item  template  37- 15 
menu  item  template,  as  resource  E- 

54 
menu  item,  naming  37-  30,  31 
menu  record,  changes  37-  6 
menu  template  37- 18 
menu  template,  as  resource  E-  50 
menu  title,  setting  37-  29 
menus 

adding  items  37-  23 

creating  37-  24 
menus,  custom,  and  caching  37-  7 
menus,  scrolling  37-  5 
message  center  51- 14 
message  text,  in  alert  windows  52-  8 
MessageByName  51- 14 
MIDI  clock 

operation  38-  6 

reading  cunent  frequency  38-  48 

reading  cunent  value  38-  48 

setting  base  value  38-  33 

setting  frequency  38-  35 

starting  38- 34 

stopping  38-  34 
MIDI  clock  38-  23, 33 
MIDI  commands,  Note  Sequencer 

40-19 
MIDI  data 

ignoring  System  Exclusive  data 
38-42 

packet  format  38-  7 

raw  data  mode  38-  8 

reading  38-  49 

sending  and  receiving  38-  6,  24, 
37-42, 46-47 

writing  38-  51 
MIDI  data  input,  starting  38-  38 
MIDI  data  input,  stopping  38-  39 
MIDI  data  mode,  setting  38-  40,  41 
MIDI  data  output,  starting  38-  39 
MIDI  data  output,  stopping  38-  39 
MIDI  error  vector,  setting  38-  37 
MIDI  input  buffer,  setting  38-  37 
MIDI  output  buffer,  setting  38-  38 
MIDI  real-time  command  vector, 
setting  38-  36 
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MIDI  System  Exclusive  data  38-  42 
MIDI  time-stamps 

setting  base  value  38-  33 

setting  frequency  38-  35 

starting  38-  34 

stopping  38-  34 
MIDI  time-stamps  38-  6,  23 
MIDI  Tool  Set 

AppleTalk  38-  22 

fast  access  to  tool  calls  38-  20 

interrupts  38-  22 

loading  and  unloading  device 
drivers  38-  43 

service  routines 

input  data  routine  38-  9, 12 

output  data  routine  38-  9, 

13 

real-time  command 

routine  38-  9, 10, 36 

real-time  error  routine  38- 

9,11,37 
service  routines  38-  9 
shutting  down  38-  28 
starting 

sample  code  38- 14 
starting  38- 6, 27 
tool  dependencies  38-  7,  23 
MIDI,  Note  Sequencer  and  40-  4 
MidiBootlnit  38-  26 
MidiChannelPressure  command, 

Note  Sequencer  40-  20 
MidiClock  38-  33 
MidiControl  38-  36 
MidiControlChange  command,  Note 

Sequencer  40-  20 
MidiDevice  38-  43 
Midilnfo  38-  46 
MidiNoteOff  command,  Note 

Sequencer  40-  20 
MidiNoteOn  command,  Note 

Sequencer  40-  21 
MidiPitchBend  command,  Note 

Sequencer  40-  21 
MidiPolyphonicKeyPressure 

command,  Note  Sequencer 
40-22 
MidiProgramChange  command, 

Note  Sequencer  40-  22 
MidiReadPacket  38-  49 
MidiReset  38-  30 

MidiSelectChannelMode  command, 
Note  Sequencer  40-  22 


MidiSetSysExlHighWord  command, 

Note  Sequencer  40-  23 
MidiShutDown  38-  28 
MidiStartUp  38-  27 
MidiStatus  38-  31 
MidiSystemCommon  command, 

Note  Sequencer  40-  24 
MidiSystemExclusive  command, 

Note  Sequencer  40-  23 
MidiSystemRealTime  command, 

Note  Sequencer  40-  25 
MidiVersion  38-  29 
MidiWritePacket  38-  51 
moreFlags,  TEParamBlock  record 

field  49- 40 
mouse  interface,  TextEdit  49- 11 
mouse,  tracking  in  TextEdit  records 

49-76 
multifile  reply  record,  Standard  File 

48-8 
multipart  controls,  control  definition 

procedure  routines  28- 19 
Musical  Instrument  Digital  Interface 

(MIDI)  38-  2 

N 

naming  print  documents  42-  3,  6,  9 
network  printer,  getting  information 

about  42- 10 
new  desk  accessories  29-  2, 9 
NewControl2  28-  33 
NewList2  35-6 
NewMenu2  37-  24 
NewMenuBar2  37-25 
NewWindow2  52-  32 
NextMember2  35-  8 
note  commands,  Note  Sequencer 

40-7 
Note  Sequencer 

command  interpreter  40-  5 

initializing  40-  38 

interrupt  mode  40-  39 

tool  dependencies  40-  3 

update  rate  40-  39 
Note  Sequencer  commands 

control  commands  40-  10 

MIDI  commands  40-  19 

note  commands  40-  7 

register  commands  40-16 
note  sequences 

controlling  tempo  40-  49 

getting  information  about  40-  46 

playing  40-  60 


starting  40- 53,  55 

stopping  40-  62 

stopping  and  starting  40-  45 

timing  40-  3 

turning  off  notes  40-  48 
note  sequences  40-  26 
Note  Synthesizer 

setting  update  rate  41- 15,  26 

sound  envelopes  41-4 

starting  41- 15 

starting  and  using  41-2 

tool  dependencies  41-  2 
Note  Synthesizer  instruments  41-  6 
NoteOff  41-  2, 23 
NoteOff  command,  Note  Sequencer 

40-9 
NoteOn41-2,24 
NoteOn  command,  Note  Sequencer 

40-9 
notes 

turning  off  41-  20,  23 

turning  on  41-  24 
notes  off,  turning  Note  Sequencer  40- 

15 
notify  multipart,  control  definition 

procedure  routine  28- 19 
NotifyCtls28-35 
NSBootlnit  41- 14 
NSReset  41- 18 
NSSetUpdateRate  41-  26 
NSSetUserUpdateRtn  41-  27 
NSShutDown  41-16 
NSStartUp  41- 15 
NSStatus41-19 
NSVersion  41- 17 

O 

OpenResourceFile  45-  60 
oscillator  enable  register 

Sound  Tool  Set  and  47- 16 
oscillator  interrupt  register 

Sound  Tool  Set  and  47- 16 
oscillators 

Sound  Tool  Set  and  47-  9 
oscillators,  used  to  form  generators 

41-10 
out-of-memory  queue  36-  2 
out-of-memory  routines  36-  2,  8,  10 
out-of-memory  routines,  and 
TextEdit  49-  78 


PackBytes  39-  2 
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PackBytes  F- 13 

page  orientation,  getting  information 

about  42-  7 
Pascal  strings,  as  resource  E-  56 
password  fields  34-  2 
pasting  text  with  TextEdit  49- 110 
pattern  filling  43-  3, 8 
patterns  (drawing) 

640  mode  43-  3 
patterns,  Note  Sequencer  40-  26 
phrase  done  flag  40-  26 
phrases,  Note  Sequencer  40-  26 
picture  control 

control  record  28- 110 
picture  control  28-  6,  9 
picture  control  template  E-  24 
Pitch  Bend  command,  Note 

Sequencer  40- 13 
pitchbend,  Note  Synthesizer 

parameter  41- 12 
pitchbendRange,  Note  Synthesizer 

parameter  41-  8 
PMLoadDriver  42-  4 
PMStartUp  Print  Manager  call  42-  3 
PMUnloadDriver  42-  5 
pop-up  control  28- 10 
pop-up  menu  control 

control  record  28-  113 

control  template  28-  63 
pop-up  menu  control  28-  6 
pop-up  menu  control  template  E- 

26 
pop-up  menus 

defining  and  using  37- 12 

with  other  Menu  Manager  calls 
37-13 
pop-up  menus  37-  8 
PopUpMenuSelect  37-27 
port  state  and  Control  Manager  tool 

calls  28-3 
port  state  and  Control  Manager  tool 

calls  F- 5 
PostScript  fonts,  printing  with  42-  3 
PrChoosePrinter  Print  Manager  call 

42-3 
PrGetDocName  42-  6 
PrGetNetworkName  42- 10 
PrGetPgOrientation  42-  7 
PrGetPortDvrName  42-  11 
PrGetPrinterDvrName  42-  12 
PrGetPrinterSpecs  42-  8 
PrGetUserName  42- 13 
PrGetZoneName  42- 14 
print  documents,  naming  42-  3,  6,  9 


Print  Manager  and  List  Manager  42-  3 
print  zone  name,  getting  information 

about  42- 14 
printer  driver,  getting  information 

about  42- 12 
printer  port  driver,  getting 

information  about  42-  11 
printer,  getting  information  about  42- 

8 
printing  TextEdit  text  49- 108 
prioritylncrement,  Note  Synthesizer 

parameter  41-8 
PrJobDialog  Print  Manager  call  42-  2 
PrJobDialog  Print  Manager  call  F- 14 
Program  Change  command,  Note 

Sequencer  40- 14 
PrPicFile  Print  Manager  call  42-  2 
PrPicFile  Print  Manager  call  F- 14 
PrPixelMap  Print  Manager  call  42-  2 
PrPixelMap  Print  Manager  call  F- 14 
PrSetDocName  42-  9 


queues  and  queue  handling  39-  3 
queues,  adding  entries  39-  5 
queues,  deleting  entries  39-  6 

R 

radio  button  control 
control  template  28-  69 
extended  control  record  28-118 
new  features  28- 11 
radio  button  control  template  E-  30 
rAlertString  resource  type  E-  2 
rClInputString,  resource  type  E-  43 
rClOutputString,  resource  type  E-  44 
rControlList  resource  type  E-  3 
rControlTemplate 

check  box  control  template  E- 13 
icon  button  control  template  E- 

15 
keystroke  equivalent  E- 10 
LineEdit  control  template  E- 18 
list  control  template  E-  20 
picture  control  template  E-  24 
pop-up  menu  control  template 

E-26 
radio  button  control  template  E- 

30 
scroll  bar  control  template  E-  32 
simple  button  control  template 

E- 11 
size  box  control  template  E-  34 


standard  header  E-  5 
static  text  control  template  E-  36 
TextEdit  control  template  E-  38 
rControlTemplate  resource  type  E-  4 
rCString,  resource  type  E-  45 
readConfig  parameters,  in  ADB 

ReadKeyMicroData  call  26-  2 
readConfig  parameters,  in  ADB 

ReadKeyMicroData  call  F-  2 
ReadDOCReg47-21 
ReadMouse2  39- 10 
RealFreeMem  36-  9 
record  size,  control  definition 

procedure  routine  28- 13 
reference  types  28-  5 
register  commands,  Note  Sequencer 

40-16 
release  41- 3 
ReleaseResource  45-  62 
ReleaseROMResource  39- 10 
releaseSegment,  Note  Synthesizer 

parameter  41-7 
RemoveCDA  29-  8 
RemoveFromOOMQueue  36-  10 
RemoveFromQueue  39-  3 
RemoveFromRunQ  29-  7 
RemoveNDA  29-  9 
RemoveResource  45-  63 
removing  text,  with  TextEdit  49-  80 
replacing  text  with  TextEdit  49- 1 13 
reply  record,  Standard  File  48-  6 
ResetMember2  35-  9 
ResizeWindow  52-  4,  35 
resource  attributes 

getting  45- 50 

setting  45-  68 
resource  converters 

loading  code  resources  39-  7 

ReadResource  45-  21 

ReturnDiskSize  45-  25 

WriteResource  45-  23 
resource  converters  45-  20,  64 
resource  files 

adding  resources  45-  34 

changing  search  sequence  45- 13, 
67,69 

creating  45-  39 

current  45-  36 

current  file  45- 12 

current,  finding  45-  42 

file  ID  45- 60 

file  IDs  45- 11 

format  and  content  45- 11,  13 

free  block  layout  45- 18 
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getting  GS/OS  reference  number 
for  45- 48 

getting  resource  map  45-  46 

header  layout  45- 15 

last  file  45- 12 

map  layout  45- 16 

opening  45-  60 

reference  record  layout  45- 19 

search  sequence  45- 12 

system  28-  5 

system  45-  8, 36 
resource  files  45-  5 
resource  free  block  layout  45- 18 
resource  header  layout  45- 15 
resource  ID  45-  5 
resource  IDs 

getting  unique  45-  73 

setting  45- 70 
Resource  Manager 

getting  current  user  ID  45-  41 

starting  45- 8 
resource  map  layout  45- 16 
resource  map,  getting,  for  a  resource 

file  45- 46 
resource  names  45-  7 
resource  names,  as  resource  E-  57 
resource  reference  record  layout  45- 

19 
resource  search  sequence  45- 12 
resource  types 

counting  45-  38 

getting  by  index  45-  45 
resource  types  45-  5 
ResourceBootlnit  45-  28 
ResourceConverter  45-  20,  64 
ResourceReset  45-  32 
resources 

adding  to  resource  files  45-  34 

and  Control  Manager  28-  5 

and  Window  Manager  52-  32 

and  Window  Manager  E-  68,  72 

attributes  of  45- 9 

changing  45-  57, 75 

controlling  loading  from  disk  45- 
71 

copying  45-  40 

counting  45-  37 

defined  45-  2 

deleting  from  resource  file  45-  63 

detaching  45-  40 

finding  by  handle  45-  58 

finding  file  for  45-  52 

getting  by  index  45-  43 

getting  size  of  45-  51 


loading  45-  55 

loading  at  absolute  address  45-  53 

removing  from  memory  45-  62 

removing  from  resource  file  45- 
63 

using  45- 2, 8 

writing  to  disk  45-  76 
ResourceShutDown  45-  30 
ResourceStartUp  45-  29 
ResourceStatus  45-  33 
ResourceVersion  45-  31 
rlcon,  resource  type  E-  46 
rKTransTable,  resource  type  E-  47 
rListRef,  resource  type  E-  49 
rMenu,  resource  type  E-  50 
rMenuBar,  resource  type  E-  53 
rMenuItem,  resource  type  E-  54 
rPString,  resource  type  E-  56 
rResName,  resource  type  E-  57 
rStringlist,  resource  type  E-  59 
rText,  resource  type  E-  60 
rTextBlock,  resource  type  E-  61 
rTextBox2,  resource  type  E-  62 
rToolStartup,  resource  type  E-  63 
rTwoRects,  resource  type  E-  65 
run  item  layout  29-  3 
run  queue 

adding  run  items  29-  6 

example  29-  5 

removing  run  items  29-  7 
run  queue  29-  3 

rWindColor,  resource  type  E-  66 
rWindParaml,  resource  type  E-  68 
rWindParam2,  resource  type  E-  72 


sample  code 

application  switcher  and 

Resource  Manager  45-  26 
control  templates  28-  83 
creating  empty  menus  37-  4 
fast  access  to  MIDI  Tool  Set 

routines  38-  20 
FFStartSound  47-  5 
FFStartSound  F-  19 
note  sequence  with  relative 

addressing  40-  58 
Note  Sequencer  40-  28 
Note  Synthesizer  41-  25 
out-of-memory  routines  36-  5 
reading  time-stamped  MIDI  data 

38-16 
run  queue  29-  5 


Standard  File  dialog  templates  48- 

13 
starting  the  MIDI  Tool  Set  38- 14 
TaskMasterContent  52-  37 
TaskMasterKey  52-  40 
TextEdit  control  with  TaskMaster 

49-6 
TextEdit  control  without 
TaskMaster  49- 7 
TextEdit  record  that  is  not  a 

control  49-  9 
writing  time-stamped  MIDI  data 
38-18 
sample  rates 

Sound  Tool  Set  and  47- 10 
scroll  bar  control 

control  template  28-  71 
extended  control  record  28-121 
new  features  28- 11 
scroll  bar  control  28-  4 
scroll  bar  control  barArrowBack 

entry  28- 3 
scroll  bar  control  barArrowBack 

entry  F- 5 
scroll  bar  control  template  E-  32 
scroll  bars  and  list  controls  35-  4 
scroll  bars,  in  TextEdit  49-  28 
scrolling  menus  37-  5 
scrolling  text  in  TextEdit  49-116 
scrolling,  horizontal,  and  TaskMaster 

52-3 
search  sequence,  resource  45- 12 
SeedFill  43-  8 
selected,  list  items  35-  2 
selected,  list  items  F-  9 
selection,  clearing  TextEdit  49-  75 
selection,  copying  with  TextEdit  49- 

79 
selection,  getting  information  about 

current  TextEdit  49-  87 
selection,  getting  information  about 

styles  in  TextEdit  49- 88 
selection,  setting  the  current  TextEdit 

49- 120 
SelectMember2  35- 10 
SendEventToCtl  28-  36 
separator  character,  in  alert  windows 

52-8 
separator  characters  in  file  names  48- 

3 
SeqAllNotesOff40-48 
SeqBootlnit  40-  37 
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seqltems  (Note  Sequencer  sequence 
items)  See  Note  Sequencer: 
sequence  items  40- 

SeqReset  40-  43 

SeqShutDown  40-  41 

SeqStartUp  40-  38 

SeqStatus  40- 44 

sequences  (note)  See  note  sequences 
40- 

SeqVersion  40-  42 

Set  Register  command,  Note 
Sequencer  40- 18 

SetAutoKeyLimit  31-  6 

SetCUID  28-  38 

SetCtlMoreFlags  28-  39 

SetCtlParamPtr  28-  40 

SetCurResourceApp  45-  66 

SetCurResourceFile  45- 13, 67 

SetDefaultTPT5M7 

SetDOCReg47-23 

Setlna  40-  49 

SetlnputDevice  tool  call  50-  2 

SetlnstTabie  40-  50 

SetlnterruptState  39- 11 

SetKeyTranslation  31-  7 

SetMenuTitle2  37-29 

SetMItem2  37-30 

SetMItemName2  37-31 

SetOriginalMask  52-  3 

SetOutputDevice  tool  call  50-  2 

SetResourceAttr45-9,68 

SetResourceFileDepth  45- 13,  69 

SetResourcelD  45-  70 

SetResourceLoad  45-  71 

SetTrklnfo40-51 

SetUserSoundlRQV  47-  6 

SetVector  39-  2 

SetZoomRect  52-  2 

SetZoomRect  F-  20 

SFAUCaps  48-  27 

SFGetFile2  48-  28 

SFMultGet2  48- 30 

SFPGetFile2  48-  32 

SFPMultiGet2  48-  34 

SFPPutFile2  48-  36 

SFPutFile2  48-  39 

SFReScan  48-  41 

SFShowInvisible  48-  42 

ShowMenuBar  37-32 

ShutDownTools  51-  2, 18 

simple  button  control 
control  template  28-  49 
extended  control  record  28-  95 
new  features  28-7 


simple  button  control  template  E- 1 1 
size  box  control 

control  template  28-  73 

extended  control  record  28- 124 

new  features  28- 11 
size  box  control  color  table  28-  2 
size  box  control  color  table  F-  4 
size  box  control  template  E-  34 
size  characters,  in  alert  windows  52-  6 
SizeWindow  52-  4 
Slot  Arbiter  50-  2 

smart  cut  and  paste,  TextEdit  49-  3 
SortList2  35-ll 
sound  envelopes 

attack,  decay,  sustain,  release  41-  2 

breakpoints  and  increments  41-  4 

data  structures  41-  7 

duration  of  41- 5 

Note  Synthesizer  41-  4 
sound  envelopes  41-  2 
sound  on  the  Ilgs,  introduction  to 

47-7 
sound  tools,  version  requirements 

47-6 
sounds,  playing  47-  20 
sounds,  preparing  to  play  47- 18 
special  characters,  in  alert  window 

alert  strings  52-  9 
SpecialRect  43- 15 
Standard  File  limits  48-  2 
StartFrameDrawing  52-  36 
starting  and  stopping  tool  sets  51-  2, 

4, 18, 19 
starting  tool  sets  51- 19 
Startlnts  40-  52 
StartSeq40-53 
StartSeqRel  40-  55 
StartStop  record,  as  resource  E-  63 
StartStop  record,  starting  and 
stopping  tool  sets  51-  4 
StartUpTools  51-  2, 19 
static  text  control 

control  record  28- 127 

control  template  28-  75 
static  text  control  28-  6, 11 
static  text  control  template  E-  36 
StepSeq4O-60 
Stoplnts  40-  61 
stopping  tool  sets  51- 18 
StopSeq  40-  62 
Styleltem,  TextEdit  record  layout  49- 

62 
styles,  changing  TextEdit  49- 124 


subsequences,  in  compression  27- 

12,17 
SuperBlock,  TextEdit  record  layout 

49-63 
SuperHandle,  TextEdit  record  layout 

49-64 
Superltem,  TextEdit  record  layout 

49-65 
sustain41-  3 

synthesizer  voices  47-  9 
system  resource  file  28-  5 


tab,  control  definition  procedure 

routine  28- 18 
Tabltem,  TextEdit  record  layout  49- 

66 
target  control  28-  5, 18,  25, 31, 32,  36 
target  controls  49-  2, 74, 81 
target,  control  definition  procedure 

routine  28- 15 
task  record,  new  definition  52- 17 
TaskMaster52-17,37,39,40 
TaskMaster  result  codes  52- 12 
TaskMasterContent  52-  37 
TaskMasterDA  52-  39 
TaskMasterKey  52-  40 
TEActivate  49-  74 
TEBootlnit  49-  69 
TEClear  49-  75 
TEClick  49-  76 
TEColorTable,  TextEdit  data 

structure  49-  30 
TECompactRecord  49-  78 
TECopy  49-  79 
TECut  49-  80 
TEDeactivate  49-  81 
TEFormat,  TextEdit  data  structure 

49-34 
TEGetDefProc  49-  82 
TEGetlntemalProc  49-  83 
TEGetLastError  49-  84 
TEGetRuler  49-  85 
TEGetSelection  49-  87 
TEGetSelectionStyle  49-  88 
TEGetText  49-  91 
TEGetTextlnfo  49-  95 
TEIdle  49-  98 
TEInsert  49-  99 
TEKey  49- 102 
TEKill  49- 103 
templates 
control  28-6 


X-8       Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


templates,  Menu  Manager 
menu  bar  template  37-  20 
menu  item  template  37- 15 
menu  template  37- 18 

templates,  Menu  Manager  37- 15-20 

Tempo  command,  Note  Sequencer 
40-14 

TENew  49- 104 

TEOffsetToPoint  49- 106 

TEPaintText  49- 108 

TEParamBlock  49-  3 

TEParamBlock,  TextEdit  data 
structure  49-  36 

TEParamBlock,  TextEdit  record  49- 
104 

TEPaste49-110 

TEPointToOfFset49-lll 

TERecord 

filterProcfield49-53 
handles  to  49- 11 
keyFilter  field  49-  58 
textFlagsfield49-53 
theBufferHPosfield49-58 
theBufferVPosfield49-58 
theFilterRectfield49-58 
theKeyRecord  field  49-  58 
wordBreakHook  field  49-  57 
wordWrapHook  field  49-  58 

TERecord  49-  3 

TERecord,  TextEdit  record  layout  49- 
47 

TEReplace  49- 113 

TEReset  49-  72 

terminator  character,  in  alert 
windows  52-  8 

TERuler,  TextEdit  record  layout  49- 
44 

TEScroll  49- 116 

TESetRuler49-H8 

TESetSelection  49- 120 

TESetText  49- 121 

TEShutDown  49-  71 

TEStartUp  49-  70 

TEStatus  49-  73 

TEStyle,  TextEdit  record  layout  49-  46 

TEStyleChange  49- 124 

TEUpdate  49- 127 

TEVersion  49-  72 

text  justification  in  pictures  44-  2 

TextBlock,  TextEdit  record  layout  49- 
67 

TextEdit 

activating  records  49-  74 
and  Control  Manager  49- 14 


changing  style  information  49- 

124 
clearing  selection  49-  75 
compressing  records  49-  78 
copying  text  49-  79 
creating  new  records  49- 104 
current  selection  49-  87,  88 
custom  scroll  bars  49-  28 
cutting  text  49-  80 
data  structures  49-  29-68 
deactivating  records  49-  81 
disposing  of  records  49- 103 
error  processing  49-  84 
features  49-  2 
filter  procedures  49- 15-27 
generic  filter  procedure 
doEraseBuffer  49- 18 
doEraseRect  49- 17 

doRectChanged  49- 19 
generic  filter  procedure  49- 16 
hook  routines  49- 15-27 
inserting  text  49-  99 
justification  49-  3 
keyboard  and  mouse  interface 

49-11 
KeyRecord  49-  59 
keystroke  filter  procedure  49-  20 
keystroke  processing  49- 102 
pasting  text  49- 110 
printing  with  49- 108 
replacing  text  49- 113 
scrolling  text  49- 116 
setting  current  selection  49- 120 
smart  cut  and  paste  49-  3 
StyleItem49-62 
SuperBlock  49-  63 
SuperHandle  49-  64 
Superltem  49-  65 
Tabltem  49-  66 
TEColorTable  49-  30 
TEFormat  49-  34 
TEParamBlock  49-  36 
TERecord  49-  47 
TERuler  49-  44 
TEStyle  49- 46 
TextBlock  49-  67 
TextList  49-  68 
tracking  the  mouse  49-  76 
word  break  hook  routine  49-  26 
word  wrap  hook  routine  49-  24 
TextEdit  control 

control  record  28- 131 
control  template  28-  77 


TextEdit  control  28-  6, 12 
TextEdit  control  template  E-  38 
TextEdit  records  49-  2 
textFlags,  TEParamBlock  record  field 

49-41 
textFlags,  TERecord  field  49-  53 
TextList,  TextEdit  record  layout  49-  68 
theBufferHPos,  TERecord  field  49- 

18,58 
theBufferVPos,  TERecord  field  49- 18, 

58 
theChar,  TERecord  KeyRecord  field 

49-  20, 23 
theFilterRect,  TERecord  field  49- 17, 

18, 19, 58 
thelnputHandle,  TERecord 

KeyRecord  field  49-  20,  23 
theKeyRecord,  TERecord  field  49-  58 
theModifiers,  TERecord  KeyRecord 

field  49- 20, 23 
theOpCode,  TERecord  KeyRecord 

field  49- 22, 23 
time-stamps,  reading  MIDI  data  with 

38-16 
time-stamps,  writing  MIDI  data  with 

38-18 
timing,  in  note  sequences  40-  3 
title,  menu,  setting  37-  29 
tmContentControls  taskMask  flag  52- 

37 
tool  set  dependencies  51-  8 
tool  set  numbers  51-  6 
Turn  Notes  Off  command,  Note 

Sequencer  40- 15 
turning  off  notes  in  sequences  40-  48 
type  1  pop-up  menus  37- 10 
type  2  pop-up  menus  37- 10 

U 

UniqueResourcelD  45-  73 
UnPackBytes  39-  2 
UnPackBytes  F- 13 
UpdateResourceFile  45-  75 
user  ID,  getting,  for  Resource 

Manager  45-  41 
user  name,  getting  information 

about  42- 13 


vectors,  new  system  39-  2 
version  numbers,  tool  set  51-  2 
vertBar,  TEParamBlock  field  49-  28 
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Vibrato  Depth  command,  Note 

Sequencer  40-15 
vibratoDepth,  Note  Synthesizer 

parameter  41-  8, 13 
vibratoSpeed,  Note  Synthesizer 

parameter  41-  8 
voices,  synthesizer  47-  9 
volume  register 

Sound  Tool  Set  and  47- 13 

W 

wave  forms 

Sound  Tool  Set  and  47- 11 
waveform  data  sample  register 
Sound  Tool  Set  and  47- 13 
waveform  table  register 

Sound  Tool  Set  and  47- 13 
waveList,  Note  Synthesizer  parameter 

41-9 
WindNewRes  52-  2 
WindNewRes  F-  20 
window  change,  control  definition 

procedure  routine  28-  20 
window  record,  new  definition  52- 

14 
window  size,  control  definition 

procedure  routine  28- 17 
word  break,  in  TextEdit  49-  26 
word  wrap,  in  TextEdit  49-  24 
wordBreakHook,  TERecord  field  49- 

26,57 
wordWrapHook,  TERecord  field  49- 

24,58 
WriteResource  45-  76 
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